From 472ec6bafcfb0fb171f8598ecd3ca4bb62e76d7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20=C5=81oskot?= Date: Thu, 21 Jun 2018 16:18:00 +0200 Subject: [PATCH] [doc] Describe development workflow using CMake [ci skip] Add "Using Faber" section. --- CONTRIBUTING.md | 230 +++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 186 insertions(+), 44 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 517a2fb3a..4a12378e1 100644 --- 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_