Adding upstream version 14.2.21.upstream/14.2.21upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 600 insertions, 0 deletions

diff --git a/src/boost/libs/gil/CONTRIBUTING.md b/src/boost/libs/gil/CONTRIBUTING.md
new file mode 100644
index 00000000..f4da98c8
--- /dev/null
+++ b/src/boost/libs/gil/CONTRIBUTING.md
@@ -0,0 +1,600 @@
+# Contributing to Boost.GIL
+
+Boost.GIL is a member of [Boost](https://www.boost.org) libraries.
+
+If you wish to contribute a new feature or a bug fix,
+please follow the workflow explained in this document.
+
+## Table of Content
+
+- [Prerequisites](#prerequisites)
+- [Pull Requests](#pull-requests)
+- [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](#3-fork-boostgil-repository-on-github)
+  - [4. Submit a pull request](#4-submit-a-pull-request)
+  - [5. Update your pull request](#5-update-your-pull-request)
+- [Development](#development)
+  - [Install dependencies](#install-dependencies)
+  - [Using Boost.Build](#using-boostbuild)
+  - [Using CMake](#using-cmake)
+  - [Using Faber](#using-faber)
+  - [Running clang-tidy](#running-clang-tidy)
+- [Guidelines](#guidelines)
+
+## Prerequisites
+
+- C++11 compiler
+- Build and run-time dependencies for tests and examples:
+  - Boost.Filesystem
+  - Boost.Test
+  - Headers and libraries of libjpeg, libpng, libtiff, libraw for the I/O extension.
+- 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://boostorg.github.io/build/) for the first time.
+
+## Pull Requests
+
+- **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
+  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
+  infrastructure configuration via direct commits (CAUTION!)
+- **DO NOT** mix independent, unrelated changes in one PR.
+  Separate unrelated fixes into separate PRs, especially if they are in different components
+  (e.g. core headers versus extensions).
+  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.
+- **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
+  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].
+- **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
+  close issues when the PR is merged.
+- **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
+  the Continuous Integration (CI) system before it'll be merged.
+- **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
+  to track changes.
+- **DO** assume that the [Squash and Merge] will be used to merge your commit unless you
+  request otherwise in the PR.
+- **DO** NOT fix merge conflicts using a merge commit. Prefer git rebase.
+- **DO** NOT submit changes to the original legacy tests, see
+  [test/legacy/README.md](test/legacy/README.md).
+
+### Merging Pull Requests (for maintainers with write access)
+
+- **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
+  history than [Create a Merge Commit]. Reasons that PR authors may request the true
+  merge recording a merge commit 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.
+  - Contributor is using an e-mail address other than the primary GitHub address
+    and wants that preserved in the history.
+    Contributor must be willing to squash the commits manually before acceptance.
+
+## Getting started with Git workflow
+
+First, you need learn some minimal basics of the
+[modular Boost](https://svn.boost.org/trac/boost/wiki/ModularBoost)
+super-project workflow.
+
+The following steps are based on the official Boost
+[Getting Started](https://github.com/boostorg/boost/wiki/Getting-Started).
+
+**NOTE:** For brevity, commands below use notation for POSIX-like operating
+systems and you may need to tweak them for Windows systems.
+
+### 1. Clone Boost super-project
+
+The preparation involves the following steps:
+
+1. Clone the Boost super-project
+
+    ```shell
+    git clone --recurse-submodules --jobs 8 https://github.com/boostorg/boost.git
+    ```
+
+2. Switch the Boost super-project to desired branch, `master` or `develop`
+
+    ```shell
+    cd boost
+    git checkout master
+    ```
+
+    **TIP:** [Modular Boost Library Maintenance](https://svn.boost.org/trac10/wiki/StartModMaint)
+    guide, for more realistic test environment, recommends to develop and test
+    individual Boost library against other Boost libraries as defined by
+    the Boost super-project `master` branch:
+
+    ```shell
+    cd boost
+    git checkout master
+    git pull
+    git submodule update --init --recursive --jobs 8
+    ```
+
+3. Build the `b2` driver program for Boost.Build engine.
+
+    ```shell
+    ./bootstrap.sh
+    ./b2 --version
+    ```
+
+    **TIP:** For more convenient path-less invocation, you can copy the `b2`
+    program to a location in your `PATH`.
+
+4. Optionally, create full content of `/boost` virtual directory with
+all Boost headers linked from the individual modular Boost libraries.
+If you skip this step, executing `b2` to run tests will automatically
+create the directory with all headers required by Boost.GIL and tests.
+
+    ```shell
+    ./b2 -j8 headers
+    ```
+
+**TIP:** If something goes wrong, you end up with incomplete or accidentally
+modified files in your clone of the super-project repository, or you simply
+wish to start fresh, then you can clean and reset the whole repository and
+its modules:
+
+```shell
+git clean -xfd
+git submodule foreach --recursive git clean -xfd
+git reset --hard
+git submodule foreach --recursive git reset --hard
+git submodule update --init --recursive --jobs 8
+```
+
+### 2. Checkout Boost.GIL development branch
+
+Regardless if you decide to develop again `master` (recommended) or `develop`
+branch of the Boost super-project, you should *always* base your contributions
+(i.e. topic branches) on Boost.GIL `develop` branch.
+
+1. Go to the Boost.GIL library submodule.
+
+    ```shell
+    cd libs/gil
+    ```
+
+2. Checkout the `develop` branch and bring it up to date
+
+    ```shell
+    git checkout develop
+    git branch -vv
+    git pull origin develop
+    ```
+
+### 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)
+repository from where you will be able to submit new contributions as
+[pull requests](https://help.github.com/articles/about-pull-requests/).
+
+Add your fork as git remote to the Boost.GIL submodule:
+
+```shell
+cd libs/gil
+git remote add <username> https://github.com/<username>/gil.git
+```
+
+or, if you cloned from your fork already, add the upstream as `origin` remote:
+
+```shell
+git remote add upstream https://github.com/boostorg/gil.git
+# or
+git remote rename origin <username>
+git remote add origin https://github.com/boostorg/gil.git
+```
+
+### 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).
+
+**IMPORTANT:** Pull Requests *must* come from a branch based on `develop`,
+and *never* on `master`.
+
+**NOTE:** The branching workflow model
+[Boost recommends](https://svn.boost.org/trac10/wiki/StartModWorkflow)
+is called Git Flow.
+
+For example:
+
+```shell
+cd libs/gil
+git checkout develop
+git checkout -b feature/foo
+```
+
+Now, you are set to to develop a new feature for Boost.GIL,
+then [git add](https://git-scm.com/docs/git-add) and
+[git commit](https://git-scm.com/docs/git-commit) your changes.
+
+Once it's finished, you can submit it as pull request for review:
+
+```shell
+cd libs/gil
+git checkout feature/foo
+git push <username> feature/foo
+```
+
+Finally, sign in to your GitHub account and
+[create a pull request](https://help.github.com/articles/creating-a-pull-request/).
+
+Your pull request will be automatically built and tests will run on Travis CI
+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.
+
+### 5. Update your pull request
+
+Depending on actual purpose of the update, you can follow a different
+strategy to update your pull request:
+
+- Use `git commit --amend`, `git rebase` and `git push --force` when your
+   pull request is still *work-in-progress* and not ready for review yet.
+- Use `git commit`, `git merge` and `git push` to update your pull request
+   during review, in response to requests from reviewers.
+
+**NOTE:** Once review of your work has started, you should not rebase your work.
+You should create new commits and update your topic branch. This helps with
+traceability in the pull request and prevents the accidental history breakage.
+Those who review your work may be fetching it into their fork for local review.
+
+#### Synchronise pull request branch
+
+Keep your topic branch up to date and synchronized with the upstream `develop` branch:
+
+```shell
+cd libs/gil
+git checkout develop
+git pull origin develop
+git checkout feature/foo
+```
+
+If review of your work has not started, *prefer* to merge:
+
+```shell
+git merge develop
+git push <username> feature/foo
+```
+
+If your PR is still *work-in-progress*, you may rebase if you like:
+
+```shell
+git rebase develop
+git push --force <username> feature/foo
+```
+
+#### Amend last commit of pull request
+
+If your pull request is a *work-in-progress* and has not been reviewed yet,
+you may amend your commit or rebase onto the `develop` branch:
+
+```shell
+cd libs/gil
+git checkout feature/foo
+git add -A
+git commit --amend
+git push --force <username> feature/foo
+```
+
+#### Add new commits to pull request
+
+In order to update your pull request, for example in response to a change
+request from reviewer, just add new commits:
+
+```shell
+cd libs/gil
+git checkout feature/foo
+git add -A
+git commit -m "Fix build Travis CI failures"
+git push <username> feature/foo
+```
+
+## Development
+
+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](example/README.md) programs have to be compiled.
+
+By default, Boost.GIL uses Boost.Build to build all the executables.
+
+We also provide configuration for two alternative build systems:
+
+- [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.
+
+### Install dependencies
+
+Boost.GIL tests and examples use the GIL I/O extension which depends on
+third-party libraries for read and write support of specific image formats:
+
+```shell
+sudo apt-get install libjpeg-dev libpng-dev libtiff5-dev libraw-dev
+```
+
+### 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 -j8 test/core
+```
+
+Run all tests for selected extension (from Boost root directory, as alternative):
+
+```shell
+./b2 -j8 libs/gil/test/io
+./b2 -j8 libs/gil/test/numeric
+./b2 -j8 libs/gil/test/toolbox
+```
+
+Run I/O extension tests bundled in target called `simple`:
+
+```shell
+./b2 libs/gil/test/io//simple
+```
+
+### Using CMake
+
+Maintainer: [@mloskot](https://github.com/mloskot)
+
+**WARNING:** The CMake configuration is only provided for convenience
+of contributors. It does not export or install any targets, deploy
+config files or support subproject workflow.
+
+**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 -j8 headers
+  ./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
+  ```
+
+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.
+
+**TIP:** For the lightweight setup, prefer latest release of Boost.
+
+For available custom CMake options, open the top-level `CMakeLists.txt`
+and search for `option`.
+
+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
+    ```
+
+- 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 ..
+    ```
+
+    **TIP:** By default, tests and [examples](example/README.md) are compiled using
+    the minimum required C++11.
+    Specify `-DCMAKE_CXX_STANDARD=14|17|20` to use newer version.
+    For more CMake options available for GIL, check `option`-s defined
+    in the top-level `CMakeLists.txt`.
+
+    **TIP:** If CMake is failing to find Boost libraries, especially built
+    with `--layout=versioned`, you can try a few hacks:
+      - option `-DBoost_ARCHITECTURE=-x64` to help CMake find Boost 1.66 and above
+        add an architecture tag to the library file names in versioned build
+        The option added in CMake 3.13.0.
+      - option `-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
+        (i.e. `libboost_unit_test_framework-gcc5-mt-x64-1_69` and not `-gcc55-`).
+        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.
+
+- 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
+
+    ```shell
+    ctest --show-only | grep Test
+    ```
+
+- Run selected test with CTest
+
+    ```shell
+    ctest -R gil.tests.core.pixel
+    ```
+
+#### CMake configuration for Visual Studio
+
+We provide [example/cmake/CMakeSettings.json](https://github.com/boostorg/gil/blob/develop/example/cmake/CMakeSettings.json)
+with reasonable default settings for the [CMake support in Visual Studio](https://go.microsoft.com//fwlink//?linkid=834763).
+See [example/cmake/README.md](example/cmake/README.md) for more details.
+
+#### CMake configuration for Visual Studio Code
+
+We provide [example/cmake/cmake-variants.yaml](https://github.com/boostorg/gil/blob/develop/example/cmake/cmake-variants.yaml)
+with reasonable default settings for the [CMake Tools](https://github.com/vector-of-bool/vscode-cmake-tools) extension.
+See [example/cmake/README.md](example/cmake/README.md) for more details.
+
+### Using Faber
+
+Maintainer: [@stefanseefeld](https://github.com/stefanseefeld)
+
+*TODO:* _Describe_
+
+### Running clang-tidy
+
+[clang-tidy](http://clang.llvm.org/extra/clang-tidy/) can be run on demand to
+diagnose or diagnose and fix or refactor source code issues.
+
+Since the CMake configuration is provided for building tests and [examples](example/README.md),
+it is easy to run `clang-tidy` using either the integration built-in CMake 3.6+
+as target property `CXX_CLANG_TIDY` or the compile command database which
+can be easily generated.
+
+#### Linting
+
+This mode uses the CMake built-in integration and runs `clang-tidy` checks configured
+in [.clang-tidy](https://github.com/boostorg/gil/blob/develop/.clang-tidy).
+All custom compilation warning levels (e.g. `-Wall`) are disabled and
+compiler defaults are used.
+
+```shell
+cd libs/gil
+cmake -S . -B _build -DGIL_USE_CLANG_TIDY=ON
+
+# all targets
+cmake --build _build
+
+# selected target
+cmake --build _build --target test_headers_all_in_one
+```
+
+#### Refactoring
+
+**WARNING:** This is advanced processing and depending on checks, it may fail to deliver
+expected results, especially if run against all configured translation units at ones.
+
+1. Generate `compile_commands.json` database
+
+    ```shell
+    cd libs/gil
+    cmake -S . -B _build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+    ```
+
+2. Edit `compile_commands.json` and remove entries of commands for all but the `.cpp`
+    files you wish to refactor. For example, keep `test_headers_all_in_one.cpp` only
+    to refactor all headers.
+
+3. Run the parallel `clang-tidy` runner script to apply the desired checks (and fixes)
+    across the library source code:
+
+    ```shell
+    run-clang-tidy.py -p=_build -header-filter='boost\/gil\/.*' -checks='-*,modernize-use-using' -fix > cl.log 2>&1
+    ```
+
+## Guidelines
+
+Boost.GIL is a more than a decade old mature library maintained by several
+developers with help from a couple of dozens contributors.
+It is important to maintain consistent design, look and feel.
+Thus, below a few basic guidelines are listed.
+
+First and foremost, make sure you are familiar with the official
+[Boost Library Requirements and Guidelines](https://www.boost.org/development/requirements.html).
+
+Second, strive for writing idiomatic C++11, clean and elegant code.
+
+**NOTE:** *The Boost.GIL source code does not necessary represent clean and elegant
+code to look up to. The library has recently entered the transition to C++11.
+Major refactoring overhaul is ongoing.*
+
+Maintain structure your source code files according to the following guidelines:
+
+- Name files in meaningful way.
+- Put copyright and license information in every file
+- 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
+  file comments (eg. no `\file` for Doxygen), revision information, etc.
+- In header, put `#include` guard based on header path and file name
+
+    ```cpp
+    #ifndef BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP
+    #define BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP
+    ...
+    #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.
+
+[status/work-in-progress]: https://github.com/boostorg/gil/labels/status%2Fwork-in-progress
+[refer]: https://help.github.com/articles/autolinked-references-and-urls/
+[keywords]: https://help.github.com/articles/closing-issues-using-keywords/
+[mention]: https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-people-and-teams
+[squash and merge]: https://help.github.com/articles/merging-a-pull-request/
+[create a merge commit]: https://help.github.com/articles/merging-a-pull-request/