boost/gil
2
0
Fork 0
mirror of https://github.com/boostorg/gil.git synced 2026-01-19 04:12:11 +00:00
Code Issues Projects Releases Wiki Activity

Add Markdown linting with Node package markdownlint [ci skip]

Browse Source
This commit is contained in:
Mateusz Łoskot
2019-11-04 23:54:09 +01:00
parent cb5b2e0ece
commit 9f5f24affd
3 changed files with 100 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.markdownlint.json Normal file
View File

@@ -0,0 +1,8 @@
{
"default": true,
"MD013": false,
"MD026": false,
"MD024": false,
"MD029": {"style": "ordered"},
"MD041": false
}

172
CONTRIBUTING.md
View File

@@ -7,32 +7,32 @@ please follow the workflow explained in this document.
## Table of Content ## Table of Content
* [Prerequisites](#prerequisites) - [Prerequisites](#prerequisites)
* [Pull Requests](#pull-requests) - [Pull Requests](#pull-requests)
* [Getting started with Git workflow](#getting-started-with-git-workflow) - [Getting started with Git workflow](#getting-started-with-git-workflow)
* [1. Clone Boost super-project](#1-clone-boost-super-project) - [1. Clone Boost super-project](#1-clone-boost-super-project)
* [2. Checkout Boost.GIL development branch](#2-checkout-boostgil-development-branch) - [2. Checkout Boost.GIL development branch](#2-checkout-boostgil-development-branch)
* [3. Fork Boost.GIL repository on GitHub](#3-fork-boostgil-repository-on-github) - [3. Fork Boost.GIL repository on GitHub](#3-fork-boostgil-repository-on-github)
* [4. Submit a pull request](#4-submit-a-pull-request) - [4. Submit a pull request](#4-submit-a-pull-request)
* [5. Update your pull request](#5-update-your-pull-request) - [5. Update your pull request](#5-update-your-pull-request)
* [Development](#development) - [Development](#development)
* [Install dependencies](#install-dependencies) - [Install dependencies](#install-dependencies)
* [Using Boost.Build](#using-boostbuild) - [Using Boost.Build](#using-boostbuild)
* [Using CMake](#using-cmake) - [Using CMake](#using-cmake)
* [Using Faber](#using-faber) - [Using Faber](#using-faber)
* [Running clang-tidy](#running-clang-tidy) - [Running clang-tidy](#running-clang-tidy)
* [Guidelines](#guidelines) - [Guidelines](#guidelines)
## Prerequisites ## Prerequisites
* C++11 compiler - C++11 compiler
* Build and run-time dependencies for tests and examples: - Build and run-time dependencies for tests and examples:
- Boost.Filesystem - Boost.Filesystem
- Boost.Test - Boost.Test
- Headers and libraries of libjpeg, libpng, libtiff, libraw for the I/O extension. - Headers and libraries of libjpeg, libpng, libtiff, libraw for the I/O extension.
* Experience with `git` command line basics. - Experience with `git` command line basics.
* Familiarity with build toolset and development environment of your choice. - Familiarity with build toolset and development environment of your choice.
* Although this document tries to present all commands with necessary options, - Although this document tries to present all commands with necessary options,
it may be a good idea to skim through the it may be a good idea to skim through the
[Boost Getting Started](https://www.boost.org/more/getting_started/index.html) [Boost Getting Started](https://www.boost.org/more/getting_started/index.html)
chapters, especially if you are going to use chapters, especially if you are going to use
@@ -40,48 +40,46 @@ please follow the workflow explained in this document.
## Pull Requests ## Pull Requests
* **DO** submit all major changes to code via pull requests (PRs) rather than through - **DO** submit all major changes to code via pull requests (PRs) rather than through
a direct commit. PRs will be CI-checked first, then reviewed and potentially merged a direct commit. PRs will be CI-checked first, then reviewed and potentially merged
by the repo maintainers after a peer review that includes at least one maintainer. by the repo maintainers after a peer review that includes at least one maintainer.
Contributors with commit access may submit trivial patches or changes to the project Contributors with commit access may submit trivial patches or changes to the project
infrastructure configuration via direct commits (CAUTION!) infrastructure configuration via direct commits (CAUTION!)
* **DO NOT** mix independent, unrelated changes in one PR. - **DO NOT** mix independent, unrelated changes in one PR.
Separate unrelated fixes into separate PRs, especially if they are in different components Separate unrelated fixes into separate PRs, especially if they are in different components
(e.g. core headers versus extensions). (e.g. core headers versus extensions).
Separate real product/test code changes from larger code formatting/dead code removal changes, Separate real product/test code changes from larger code formatting/dead code removal changes,
unless the former are extensive enough to justify such refactoring, then also mention it. unless the former are extensive enough to justify such refactoring, then also mention it.
* **DO** start PR subject with "WIP:" tag if you submit it as "work in progress". - **DO** start PR subject with "WIP:" tag if you submit it as "work in progress".
A PR should preferably be submitted when it is considered ready for review and subsequent A PR should preferably be submitted when it is considered ready for review and subsequent
merging by the contributor. Otherwise, clearly indicate it is not yet ready. merging by the contributor. Otherwise, clearly indicate it is not yet ready.
The "WIP:" tag will also help maintainers to label your PR with [status/work-in-progress]. The "WIP:" tag will also help maintainers to label your PR with [status/work-in-progress].
* **DO** give PRs short-but-descriptive names (e.g. "Add test for algorithm XXX", not "Fix #1234"). - **DO** give PRs short-but-descriptive names (e.g. "Add test for algorithm XXX", not "Fix #1234").
* **DO** [refer] to any relevant issues, and include the [keywords] that automatically - **DO** [refer] to any relevant issues, and include the [keywords] that automatically
close issues when the PR is merged. close issues when the PR is merged.
* **DO** [mention] any users that should know about and/or review the change. - **DO** [mention] any users that should know about and/or review the change.
* **DO** ensure each commit successfully builds. The entire PR must pass all tests in - **DO** ensure each commit successfully builds. The entire PR must pass all tests in
the Continuous Integration (CI) system before it'll be merged. the Continuous Integration (CI) system before it'll be merged.
* **DO** address PR feedback in an additional commit(s) rather than amending the existing - **DO** address PR feedback in an additional commit(s) rather than amending the existing
commits, and only rebase/squash them when necessary. This makes it easier for reviewers commits, and only rebase/squash them when necessary. This makes it easier for reviewers
to track changes. to track changes.
* **DO** assume that the [Squash and Merge] will be used to merge your commit unless you - **DO** assume that the [Squash and Merge] will be used to merge your commit unless you
request otherwise in the PR. request otherwise in the PR.
* **DO** NOT fix merge conflicts using a merge commit. Prefer git rebase. - **DO** NOT fix merge conflicts using a merge commit. Prefer git rebase.
* **DO** NOT submit changes to the original legacy tests, see - **DO** NOT submit changes to the original legacy tests, see
[test/legacy/README.md](test/legacy/README.md). [test/legacy/README.md](test/legacy/README.md).
### Merging Pull Requests (for maintainers with write access) ### Merging Pull Requests (for maintainers with write access)
* **DO** use [Squash and Merge] by default for individual contributions unless requested - **DO** use [Squash and Merge] by default for individual contributions unless requested
by the PR author. Do so, even if the PR contains only one commit. It creates a simpler by the PR author. Do so, even if the PR contains only one commit. It creates a simpler
history than [Create a Merge Commit].<br /> history than [Create a Merge Commit]. Reasons that PR authors may request the true
Reasons that PR authors may request the true merge recording a merge commit merge recording a merge commit may include (but are not limited to):
may include (but are not limited to): - The change is easier to understand as a series of focused commits.
Each commit in the series must be buildable so as not to break git bisect.
* The change is easier to understand as a series of focused commits.<br /> - Contributor is using an e-mail address other than the primary GitHub address
Each commit in the series must be buildable so as not to break git bisect. and wants that preserved in the history.
* Contributor is using an e-mail address other than the primary GitHub address Contributor must be willing to squash the commits manually before acceptance.
and wants that preserved in the history.<br />
Contributor must be willing to squash the commits manually before acceptance.
## Getting started with Git workflow ## Getting started with Git workflow
@@ -315,8 +313,8 @@ By default, Boost.GIL uses Boost.Build to build all the executables.
We also provide configuration for two alternative build systems: We also provide configuration for two alternative build systems:
* [CMake](https://cmake.org) - [CMake](https://cmake.org)
* [Faber](http://stefan.seefeld.name/faber/) - [Faber](http://stefan.seefeld.name/faber/)
**NOTE:** The CMake and Faber are optional and the corresponding build **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 configurations for Boost.GIL do not offer equivalents for all Boost.Build features. Most important difference to recognise is that Boost.Build will
@@ -394,15 +392,18 @@ The provided CMake configuration allows a couple of ways to develop Boost.GIL:
3. Using [cloned Boost super-project](#cloned-boost-super-project), inside modular 3. Using [cloned Boost super-project](#cloned-boost-super-project), inside modular
`libs/gil`. This mode requires prior deployment of `boost` virtual directory `libs/gil`. This mode requires prior deployment of `boost` virtual directory
with headers and stage build of required libraries, for example: with headers and stage build of required libraries, for example:
```shell
./b2 -j8 headers ```shell
./b2 -j8 variant=debug --with-test --with-filesystem stage ./b2 -j8 headers
./b2 -j8 variant=release --with-test --with-filesystem stage ./b2 -j8 variant=debug --with-test --with-filesystem stage
``` ./b2 -j8 variant=release --with-test --with-filesystem stage
or, depending on specific requirements, more complete build: ```
```shell
./b2 -j8 variant=debug,release address-model=32,64 --layout=versioned --with-test --with-filesystem stage or, depending on specific requirements, more complete build:
```
```shell
./b2 -j8 variant=debug,release address-model=32,64 --layout=versioned --with-test --with-filesystem stage
```
Using the installed Boost enables a lightweight mode for the library development, 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 inside a stand-alone clone Boost.GIL repository and without any need to clone the
@@ -415,21 +416,21 @@ and search for `option`.
Here is an example of such lightweight workflow in Linux environment (Debian-based): Here is an example of such lightweight workflow in Linux environment (Debian-based):
* Install required Boost libraries - Install required Boost libraries
```shell ```shell
sudo apt-get update sudo apt-get update
sudo apt-get install libboost-dev libboost-test-dev libboost-filesystem-dev sudo apt-get install libboost-dev libboost-test-dev libboost-filesystem-dev
``` ```
* Clone Boost.GIL repository - Clone Boost.GIL repository
```shell ```shell
git clone https://github.com/boostorg/gil.git git clone https://github.com/boostorg/gil.git
cd gil cd gil
``` ```
* Configure build with CMake - Configure build with CMake
```shell ```shell
mkdir _build mkdir _build
@@ -438,44 +439,42 @@ Here is an example of such lightweight workflow in Linux environment (Debian-bas
``` ```
**TIP:** By default, tests and [examples](example/README.md) are compiled using **TIP:** By default, tests and [examples](example/README.md) are compiled using
the minimum required C++11. the minimum required C++11.
Specify `-DCMAKE_CXX_STANDARD=14|17|20` to use newer version. Specify `-DCMAKE_CXX_STANDARD=14|17|20` to use newer version.
For more CMake options available for GIL, check `option`-s defined For more CMake options available for GIL, check `option`-s defined
in the top-level `CMakeLists.txt`. in the top-level `CMakeLists.txt`.
**TIP:** If CMake is failing to find Boost libraries, especially built with **TIP:** If CMake is failing to find Boost libraries, especially built
`--layout=versioned`, you can try a few hacks: with `--layout=versioned`, you can try a few hacks:
- option `-DBoost_ARCHITECTURE=-x64` to help CMake find Boost 1.66 and above
- `-DBoost_ARCHITECTURE=-x64` to help CMake find Boost 1.66 and above
add an architecture tag to the library file names in versioned build add an architecture tag to the library file names in versioned build
The option added in CMake 3.13.0. The option added in CMake 3.13.0.
- option `-DBoost_COMPILER=-gcc5` or `-DBoost_COMPILER=-vc141` to help CMake earlier
- `-DBoost_COMPILER=-gcc5` or `-DBoost_COMPILER=-vc141` to help CMake earlier
than 3.13 match your compiler with toolset used in the Boost library file names than 3.13 match your compiler with toolset used in the Boost library file names
(i.e. `libboost_unit_test_framework-gcc5-mt-x64-1_69` and not `-gcc55-`). (i.e. `libboost_unit_test_framework-gcc5-mt-x64-1_69` and not `-gcc55-`).
Fixed in CMake 3.13.0. Fixed in CMake 3.13.0.
- if CMake is still failing to find Boost, you may try `-DBoost_DEBUG=ON` to
get detailed diagnostics output from `FindBoost.cmake` module.
- if CMake is still failing to find Boost, you may try `-DBoost_DEBUG=ON` to - List available CMake targets
get detailed diagnostics output from `FindBoost.cmake` module.
* List available CMake targets
```shell ```shell
cmake --build . --target help cmake --build . --target help
``` ```
* Build selected target with CMake - Build selected target with CMake
```shell ```shell
cmake --build . --target gil_test_pixel cmake --build . --target gil_test_pixel
``` ```
* List available CTest targets - List available CTest targets
```shell ```shell
ctest --show-only | grep Test ctest --show-only | grep Test
``` ```
* Run selected test with CTest
- Run selected test with CTest
```shell ```shell
ctest -R gil.tests.core.pixel ctest -R gil.tests.core.pixel
@@ -568,29 +567,30 @@ Major refactoring overhaul is ongoing.*
Maintain structure your source code files according to the following guidelines: Maintain structure your source code files according to the following guidelines:
* Name files in meaningful way. - Name files in meaningful way.
* Put copyright and license information in every file - Put copyright and license information in every file
* If your changes [meet a certain threshold of originality](https://www.boost.org/users/license.html), - If your changes [meet a certain threshold of originality](https://www.boost.org/users/license.html),
add yourself to the copyright notice. Do not put any additional authorship or add yourself to the copyright notice. Do not put any additional authorship or
file comments (eg. no `\file` for Doxygen), revision information, etc. file comments (eg. no `\file` for Doxygen), revision information, etc.
* In header, put `#include` guard based on header path and file name - In header, put `#include` guard based on header path and file name
```cpp ```cpp
#ifndef BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP #ifndef BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP
#define BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP #define BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP
... ...
#endif #endif
``` ```
* Make sure each [header is self-contained](https://github.com/boostorg/gil/wiki/Include-Directives-Order), i.e. that they include all headers they need.
* All public headers should be placed in `boost/gil/` or `boost/gil/<component>/`.
* All non-public headers should be placed `boost/gil/detail` or `boost/gil/<component>/detail`.
* All public definitions should reside in scope of `namespace boost { namespace gil {...}}`.
* All non-public definitions should reside in scope of `namespace boost { namespace gil { namespace detail {...}}}`.
* Write your code to fit within **100** columns of text.
* Use [EditorConfig](https://editorconfig.org) for your editor and enable [.editorconfig](https://github.com/boostorg/gil/blob/develop/.editorconfig) to:
* Indent with **4 spaces** and no tabs.
* Trim any trailing whitespaces.
* Do not increases the indentation level within namespace.
- Make sure each [header is self-contained](https://github.com/boostorg/gil/wiki/Include-Directives-Order), i.e. that they include all headers they need.
- All public headers should be placed in `boost/gil/` or `boost/gil/<component>/`.
- All non-public headers should be placed `boost/gil/detail` or `boost/gil/<component>/detail`.
- All public definitions should reside in scope of `namespace boost { namespace gil {...}}`.
- All non-public definitions should reside in scope of `namespace boost { namespace gil { namespace detail {...}}}`.
- Write your code to fit within **100** columns of text.
- Use [EditorConfig](https://editorconfig.org) for your editor and enable [.editorconfig](https://github.com/boostorg/gil/blob/develop/.editorconfig) to:
- Indent with **4 spaces** and no tabs.
- Trim any trailing whitespaces.
- Do not increases the indentation level within namespace.
[status/work-in-progress]: https://github.com/boostorg/gil/labels/status%2Fwork-in-progress [status/work-in-progress]: https://github.com/boostorg/gil/labels/status%2Fwork-in-progress
[refer]: https://help.github.com/articles/autolinked-references-and-urls/ [refer]: https://help.github.com/articles/autolinked-references-and-urls/

11
README.md
View File

@@ -47,8 +47,9 @@ variety of images with performance similar to hand-writing for a specific image
## Documentation ## Documentation
- Latest release: https://boost.org/libs/gil - [Latest release](https://boost.org/libs/gil)
- Development: http://boostorg.github.io/gil/ - [Branch master](http://boostorg.github.io/gil/) (latest release with minor changes)
- [Branch develop](http://boostorg.github.io/gil/develop/)
See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions about how to build and See [CONTRIBUTING.md](CONTRIBUTING.md) for instructions about how to build and
run tests, examples. run tests, examples.
@@ -74,10 +75,10 @@ Optionally, in order to build and run tests and examples:
The official repository contains the following branches: The official repository contains the following branches:
* [**master**](https://github.com/boostorg/gil/tree/master) This - [**master**](https://github.com/boostorg/gil/tree/master) This
holds the most recent snapshot with code that is known to be stable. holds the most recent snapshot with code that is known to be stable.
* [**develop**](https://github.com/boostorg/gil/tree/develop) This - [**develop**](https://github.com/boostorg/gil/tree/develop) This
holds the most recent snapshot. It may contain unstable code. holds the most recent snapshot. It may contain unstable code.
## Community ## Community
@@ -106,7 +107,7 @@ with solving reported issues, especially those labelled with:
- [status/need-help](https://github.com/boostorg/gil/labels/status%2Fneed-help) - [status/need-help](https://github.com/boostorg/gil/labels/status%2Fneed-help)
- [status/need-feedback](https://github.com/boostorg/gil/labels/status%2Fneed-feedback) - [status/need-feedback](https://github.com/boostorg/gil/labels/status%2Fneed-feedback)
- [need-minimal-example ](https://github.com/boostorg/gil/labels/status%2Fneed-minimal-example) - [need-minimal-example](https://github.com/boostorg/gil/labels/status%2Fneed-minimal-example)
Any feedback from users and developers, even simple questions about how things work Any feedback from users and developers, even simple questions about how things work
or why they were done a certain way, carries value and can be used to improve the library. or why they were done a certain way, carries value and can be used to improve the library.