[doc] Describe development workflow using CMake [ci skip]

Add "Using Faber" section.
2026-01-19 04:12:11 +00:00 · 2018-06-21 16:18:00 +02:00
parent bfb0c15323
commit 472ec6bafc
1 changed files with 186 additions and 44 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,28 +10,28 @@ please follow the workflow explained in this document.
 ## Table of Content

 * [Prerequisites](#prerequisites)
-* [Getting Started](#getting-started)
-  - [1. Clone Boost super-project](#1-clone-boost-super-project)
-  - [2. Checkout Boost.GIL development branch](#2-checkout-boostgil-development-branch)
-  - [3. Run tests](#3-run-tests)
-  - [4. Fork Boost.GIL repository on GitHub](#4-fork-boostgil-repository-on-github)
-  - [5. Submit a pull request](#5-submit-a-pull-request)
-  - [6. Update your pull request](#6-update-your-pull-request)
-* [Development environment](#development-environment)
-  - [Building with Boost.Build](#building-with-boostbuild)
-  - [Building with CMake](#building-with-cmake)
+* [Getting started with Git workflow](#getting-started-with-git-workflow)
+  * [1. Clone Boost super-project](#1-clone-boost-super-project)
+  * [2. Checkout Boost.GIL development branch](#2-checkout-boostgil-development-branch)
+  * [3. Fork Boost.GIL repository on GitHub](#4-fork-boostgil-repository-on-github)
+  * [4. Submit a pull request](#5-submit-a-pull-request)
+  * [5. Update your pull request](#6-update-your-pull-request)
+* [Development](#development)
+  * [Using Boost.Build](#using-boostbuild)
+  * [Using CMake](#using-cmake)
+  * [Using Faber](#using-faber)

 ## Prerequisites

- Experience with `git` command line basics.
- Familiarity with build toolset and development environment of your choice.
- Although this document tries to present all commands with necessary options,
+* Experience with `git` command line basics.
+* Familiarity with build toolset and development environment of your choice.
+* Although this document tries to present all commands with necessary options,
  it may be a good idea to skim through the
  [Boost Getting Started](https://www.boost.org/more/getting_started/index.html)
  chapters, especially if you are going to use
-  [Boost.Build](https://www.boost.org/build/) for the first time.
+  [Boost.Build](https://boostorg.github.io/build/) for the first time.

-## Getting Started
+## Getting started with Git workflow

 First, you need learn some minimal basics of the
 [modular Boost](https://svn.boost.org/trac/boost/wiki/ModularBoost)
@@ -111,28 +111,7 @@ branch of the Boost super-project, you should always base your work
    git pull origin develop
    ```

-### 3. Run tests
-
-Try running some Boost.GIL tests to check your environment is properly configured.
-
-* Boost.GIL core tests only
-
-```shell
-cd libs/gil
-../../b2 test
-```
-
-* All Boost.GIL tests, including tests of extensions:
-
-```shell
-cd libs/gil
-../../b2
-```
-
-The [b2 invocation](https://www.boost.org/build/doc/html/bbv2/overview/invocation.html)
-explains available options like `toolset`, `variant` and others.
-
-### 4. Fork Boost.GIL repository on GitHub
+### 3. Fork Boost.GIL repository on GitHub

 Follow [Forking Projects](https://guides.github.com/activities/forking/) guide
 to get personal copy of [boostorg/gil](https://github.com/boostorg/gil)
@@ -146,7 +125,7 @@ cd libs/gil
 git remote add username https://github.com/username/gil.git
 ```

-### 5. Submit a pull request
+### 4. Submit a pull request

 All Boost.GIL contributions should be developed inside a topic branch created by
 branching off the `develop` branch of [boostorg/gil](https://github.com/boostorg/gil).
@@ -183,7 +162,7 @@ and AppVeyor (see [README](README.md) for builds status). Please, keep an eye
 on those CI builds and correct any problems detected in your contribution
 by updating your pull request.

-### 6. Update your pull request
+### 5. Update your pull request

 In simplest (and recommended) case , your the pull request you submitted earlier
 has *a single commit*, so you can simply update the existing commit with any
@@ -224,12 +203,175 @@ git commit -m "Fix variable name"
 git push username feature/foo
 ```

-## Development environment
+## Development

-### Building with Boost.Build
+Boost.GIL is a [header-only library](https://en.wikipedia.org/wiki/Header-only)
+which does not require sources compilation. Only test runners and example
+programs have to be compiled.

-TODO
+By default, Boost.GIL uses Boost.Build to build all the executables.

-### Building with CMake
+We also provide configuration for two alternative build systems:

-TODO
+* [CMake](https://cmake.org)
+* [Faber](http://stefan.seefeld.name/faber/)
+
+**NOTE:** The CMake and Faber are optional and the corresponding build
+configurations for Boost.GIL do not offer equivalents for all Boost.Build features. Most important difference to recognise is that Boost.Build will
+automatically build any other Boost libraries required by Boost.GIL as dependencies.
+
+### Using Boost.Build
+
+The [b2 invocation](https://boostorg.github.io/build/manual/develop/index.html#bbv2.overview.invocation)
+explains available options like `toolset`, `variant` and others.
+
+Simply, just execute `b2` to run all tests built using default
+`variant=debug` and default `toolset` determined for your
+development environment.
+
+**TIP:** Pass `b2` option `-d 2` to output complete action text and commands,
+as they are executed. It is useful to inspect compilation flags.
+
+If no target or directory is specified, everything in the current directory
+is built. For example, all Boost.GIL tests can be built and run using:
+
+```shell
+cd libs/gil
+../../b2
+```
+
+Run core tests only specifying location of directory with tests:
+
+```shell
+cd libs/gil
+../../b2 test
+```
+
+Run all tests for selected extension (from Boost root directory, as alternative):
+
+```shell
+./b2 libs/gil/io/test
+./b2 libs/gil/numeric/test
+./b2 libs/gil/toolbox/test
+```
+
+Run I/O extension tests bundled in target called `simple`:
+
+```shell
+./b2 libs/gil/io/test//simple
+```
+
+_TODO: Explain I/O dependencies (libjpeg, etc.)_
+
+### Using CMake
+
+Maintainer: @mloskot
+
+**NOTE:** CMake configuration does not build any dependencies required by
+Boost.GIL like Boost.Test and Boost.Filesystem libraries or any
+third-party image format libraries used by the I/O extension.
+
+The provided CMake configuration allows a couple of ways to develop Boost.GIL:
+
+1. Using Boost installed from binary packages in default system-wide location.
+2. Using Boost installed from sources in arbitrary location (CMake may need
+   `-DBOOST_ROOT=/path/to/boost/root`, see
+   [FindBoost](https://cmake.org/cmake/help/latest/module/FindBoost.html)
+   documentation for details).
+3. Using [cloned Boost super-project](#cloned-boost-super-project), inside modular
+   `libs/gil`. This mode requires prior deployment of `boost` virtual directory
+   with headers and stage build of required libraries, for example:
+    ```shell
+    ./b2 headers
+    ./b2 --with-test --with-filesystem variant=debug stage
+    ./b2 --with-test --with-filesystem variant=release stage
+    ```
+
+Using the installed Boost enables a lightweight mode for the library development,
+inside a stand-alone clone Boost.GIL repository and without any need to clone the
+whole Boost super-project.
+
+Here is an example of such lightweight workflow in Linux environment (Debian-based):
+
+* Install required Boost libraries
+
+    ```shell
+    sudo apt-get update
+    sudo apt-get install libboost-dev libboost-test-dev libboost-filesystem-dev
+    ```
+
+* Optionally, install libraries required by the I/O extension
+
+    ```
+    sudo apt-get update
+    sudo apt install libtiff-dev libpng-dev libjpeg-dev
+    ```
+
+* Clone Boost.GIL repository
+
+    ```shell
+    $ git clone https://github.com/boostorg/gil.git
+    $ cd gil
+    ```
+
+* Configure build with CMake
+
+    ```shell
+    $ mkdir _build
+    $ cd _build/
+    $ cmake ..
+    -- The CXX compiler identification is GNU 7.3.0
+    -- Check for working CXX compiler: /usr/bin/c++
+    -- Check for working CXX compiler: /usr/bin/c++ -- works
+    -- Detecting CXX compiler ABI info
+    -- Detecting CXX compiler ABI info - done
+    -- Detecting CXX compile features
+    -- Detecting CXX compile features - done
+    -- Boost version: 1.65.1
+    -- Found the following Boost libraries:
+    --   unit_test_framework
+    --   filesystem
+    --   system
+    -- Boost_INCLUDE_DIRS=/usr/include
+    -- Boost_LIBRARY_DIRS=/usr/lib/x86_64-linux-gnu
+    -- Found JPEG: /usr/lib/x86_64-linux-gnu/libjpeg.so
+    -- Found ZLIB: /usr/lib/x86_64-linux-gnu/libz.so (found version "1.2.11")
+    -- Found PNG: /usr/lib/x86_64-linux-gnu/libpng.so (found version "1.6.34")
+    -- Found TIFF: /usr/lib/x86_64-linux-gnu/libtiff.so (found version "4.0.9")
+    -- Configuring Boost.GIL core tests
+    -- Configuring Boost.GIL IO tests
+    -- Configuring Boost.GIL Numeric tests
+    -- Configuring Boost.GIL Toolbox tests
+    -- Configuring done
+    -- Generating done
+    -- Build files have been written to: /home/mloskot/gil/_build
+    ```
+
+* List available CMake targets
+
+    ```shell
+    $ cmake --build . --target help
+    ```
+
+* Build selected target with CMake
+
+    ```shell
+    cmake --build . --target gil_test_pixel
+    ```
+
+* List available CTest targets
+
+    ```
+    $ ctest --show-only | grep Test
+    ```
+* Run selected test with CTest
+
+    ```
+    ctest -R gil.tests.core.pixel
+    ```
+
+### Using Faber
+
+Maintainer: @stefanseefeld
+
+_TODO_