INSTALL

Building and Installing Cgreen
==============================

This document is incomplete. ??? are placeholders.

There are several ways to use Cgreen:

1) You want to write some tests for a personal project, but don't need to ship
   the test suite with the product, or you just want to try out CGreen.
2) You want to write some tests that will be used by other developers. This
   is the normal way to use Cgreen.
3) You want to ship working tests with a product and want to bundle Cgreen
   as the test runner.
4) You are pulling Cgreen directly from github:
   git clone git@github.com:cgreen-devs/cgreen.git

We'll walk you through these in order...

1) So you want to write a test quickly.

As a user wanting to write some quick tests, the quickest way is to
download the prebuilt binaries for your platform. Just install the
files in some private tree.

You will see a cgreen.h and both a cgreen shared object or DLL, and a
static library for your system.

Include the header and link the library as you normally would.

2) Cgreen needs to be installed to be usable by everyone.

This is the same as scenario 1, but install the files in a public
/usr/local (or equivalent). The Cgreen header should just be available
through...

#include <cgreen.h>

...and adding -lcgreen should be enough to link under gcc.

3) ???

4) You will have to carry out some additional steps if you work straight off
of a Git clone.

We are using the CMake (www.cmake.org) build system. The following
steps are called "out-of-source building", because we will build all
the project files outside of the sources directory to completely
retain the original source tree.

Assuming you have the cloned cgreen sources into a subdirectory
"cgreen" in the current directory we want to create a build directory
parallel to the source directory.

The default Makefile will create a separate 'build' directory and inside
that subdirectories for C and C++. That means that you can just do:

    $ make
    $ make test
    $ make install

You also have some options
- build with static libraries
- build HTML or PDF documentation

To enable any of these use the cmake graphical user interface (CMakeSetup
on Windows or ccmake on UNIX) to turn these options on or off.

Note on CYGWIN: Cygwin is not a WIN32 platform, but it is a
DLL-platform where libraries normally goes in the bin directory. Running
the self-tests handles this automatically but if you want to use the binaries
in the 'build'-tree you can either:

1) install before running the tests and also set PATH to include
"/usr/local/lib"

2) setting the PATH to include the build directory where the libraries are
   there is a sh-compatible command script to do that for you. From the top
   of the Cgreen source directory do:

     . cygwin-setup.sh

/Thomas 2015-12-29