From 564542979ae490882663d133958590aad55a0c52 Mon Sep 17 00:00:00 2001 From: Ruslan Baratov Date: Fri, 25 Mar 2016 07:05:41 +0700 Subject: [PATCH] Add new documentation [skip ci] --- README.md | 303 ------------------ README.rst | 11 + docs/conf.py | 305 +++++++++++++++++++ docs/contacts.rst | 11 + docs/contributing.rst | 4 + docs/creating-new.rst | 16 + docs/creating-new/cmake-dependencies.rst | 2 + docs/creating-new/cmake.rst | 6 + docs/creating-new/custom.rst | 6 + docs/donations.rst | 4 + docs/faq.rst | 2 + docs/index.rst | 55 ++++ docs/overview.rst | 20 ++ docs/overview/anything.rst | 12 + docs/overview/automatic.rst | 55 ++++ docs/overview/binaries.rst | 15 + docs/overview/cmake-only.rst | 5 + docs/overview/compatibility.rst | 9 + docs/overview/customization.rst | 14 + docs/overview/customization/build-types.rst | 4 + docs/overview/customization/config-id.rst | 51 ++++ docs/overview/customization/hunter-id.rst | 57 ++++ docs/overview/customization/toolchain-id.rst | 57 ++++ docs/overview/dry.rst | 22 ++ docs/overview/everywhere.rst | 5 + docs/overview/shareable.rst | 16 + docs/overview/what-is-it.rst | 88 ++++++ docs/overview/what-is-it.sh | 24 ++ docs/packages.rst | 11 + docs/packages/all-packages.rst | 2 + docs/quick-start.rst | 22 ++ docs/quick-start/boost-components.rst | 84 +++++ docs/quick-start/cmake.rst | 42 +++ docs/quick-start/simple.rst | 4 + docs/quick-start/uninstall.rst | 17 ++ docs/reference.rst | 12 + docs/reference/errors.rst | 2 + docs/reference/internal-modules.rst | 2 + docs/reference/internal-variables.rst | 2 + docs/reference/terminology.rst | 6 + docs/reference/user-modules.rst | 2 + docs/reference/user-variables.rst | 4 + docs/user-guides.rst | 13 + docs/user-guides/cmake-user.rst | 9 + docs/user-guides/hunter-developer.rst | 5 + docs/user-guides/hunter-user.rst | 9 + docs/user-guides/regular.rst | 2 + 47 files changed, 1126 insertions(+), 303 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/conf.py create mode 100644 docs/contacts.rst create mode 100644 docs/contributing.rst create mode 100644 docs/creating-new.rst create mode 100644 docs/creating-new/cmake-dependencies.rst create mode 100644 docs/creating-new/cmake.rst create mode 100644 docs/creating-new/custom.rst create mode 100644 docs/donations.rst create mode 100644 docs/faq.rst create mode 100644 docs/index.rst create mode 100644 docs/overview.rst create mode 100644 docs/overview/anything.rst create mode 100644 docs/overview/automatic.rst create mode 100644 docs/overview/binaries.rst create mode 100644 docs/overview/cmake-only.rst create mode 100644 docs/overview/compatibility.rst create mode 100644 docs/overview/customization.rst create mode 100644 docs/overview/customization/build-types.rst create mode 100644 docs/overview/customization/config-id.rst create mode 100644 docs/overview/customization/hunter-id.rst create mode 100644 docs/overview/customization/toolchain-id.rst create mode 100644 docs/overview/dry.rst create mode 100644 docs/overview/everywhere.rst create mode 100644 docs/overview/shareable.rst create mode 100644 docs/overview/what-is-it.rst create mode 100755 docs/overview/what-is-it.sh create mode 100644 docs/packages.rst create mode 100644 docs/packages/all-packages.rst create mode 100644 docs/quick-start.rst create mode 100644 docs/quick-start/boost-components.rst create mode 100644 docs/quick-start/cmake.rst create mode 100644 docs/quick-start/simple.rst create mode 100644 docs/quick-start/uninstall.rst create mode 100644 docs/reference.rst create mode 100644 docs/reference/errors.rst create mode 100644 docs/reference/internal-modules.rst create mode 100644 docs/reference/internal-variables.rst create mode 100644 docs/reference/terminology.rst create mode 100644 docs/reference/user-modules.rst create mode 100644 docs/reference/user-variables.rst create mode 100644 docs/user-guides.rst create mode 100644 docs/user-guides/cmake-user.rst create mode 100644 docs/user-guides/hunter-developer.rst create mode 100644 docs/user-guides/hunter-user.rst create mode 100644 docs/user-guides/regular.rst diff --git a/README.md b/README.md deleted file mode 100644 index 5eec7c968a..0000000000 --- a/README.md +++ /dev/null @@ -1,303 +0,0 @@ -Hunter -====== - -* Cross-platform package manager for C++ (based on CMake [ExternalProject][cmake-external-project]) -* Supported platforms: **Linux**, **Mac**, **Windows**, **iOS**, **Android**, **Raspberry Pi** - -### CI - -* Travis CI OSX/Linux: [![Build Status][travis-master]][travis-hunter] -* AppVeyor CI Windows: [![Build Status][appveyor-master]][appveyor-hunter] -* [Per package deep testing table](https://github.com/ingenue/hunter/branches/all) - -### What is it? - -Every Hunter [release][hunter-releases] ([Atom feed](https://github.com/ruslo/hunter/releases.atom)) archive is a meta-package with build instructions and URLs of real packages: -``` -Hunter (0.4.2) = { - Boost (1.55.0, 1.56.0, 1.57.0), - GTest (1.7.0), - OpenCV (3.0.0-beta, 2.4.11, 2.4.10), - OpenSSL (1.0.2a, 0.9.8y), - ... -} -``` - -* Default build versions can be found in [default.cmake][default-config] file and are customizable (see [Config-ID][config-id]) -* Per package versions are available in corresponding `hunter.cmake` file (e.g. [GTest][gtest-hunter]). You can pick one version that already exists or [add a new one][usr.adding.new.package] - -### Features - -* **Automatic** dependencies download - * List of dependencies is a part of CMake code of the project - * No `emerge`, `apt-get`, `brew` etc. needed before build, now it's simply `cmake --build` - * Express install instructions in terms of CMake commands instead of raw README text or other script -* **Reusable** `ExternalProject_Add` recipies ([DRY principle][dry-principle]) - * Once written formula ([build scheme][build-schemes-dir]) can be used by other projects, subprojects etc. without copying of collection of -superbuild files. Just change 2 lines of code: input parameters `SHA1`/`URL` of HunterGate command -* Several levels of build **customization**: - * [Hunter-ID][hunter-id] - list of packages and mapping version-url-sha1 - * [Config-ID][config-id] - version of package to build and build options - * [Toolchain-ID][toolchain-id] - compiler and flags - * [Build type][hunter-configuration-types] (e.g. Release/Debug) -* **Shareable** root directory with build synchronization - * Any number of projects can use root directory and add new packages simultaneously -* **Binaries from server** - * Binaries can be uploaded to server from such CI like Travis or AppVeyor and downloaded/reused later - * [Overview](https://github.com/ruslo/hunter/wiki/Uploading-binaries-to-server) -* Manage **anything** that can be downloaded by `URL` and checked with `SHA1` hash: - * C++ packages - * CMake modules - * Additional sources - * Resources (pictures, data for testing, ...) -* Backward **compatibility**. Turn Hunter off by adding one option [HUNTER_ENABLED=OFF][usr.variables-hunter-enabled] to use your old settings -* No other dependencies - **just CMake** and your environment/IDE (no need for Git or Python or anything) -* Works **everywhere**: CMake-GUI, Qt Creator, Visual Studio, Xcode, Cygwin, MinGW, Jenkins, Travis etc. - -### Notes about version of CMake - -* [3.0.0][cmake-3.0.0-release-notes] **Minimum required** - * **Buggy**, see [PR #198](https://github.com/ruslo/hunter/pull/198#issuecomment-120630877) - * Interface header-only libraries - * Sub-option `VERSION` for command `project` - * New MSVC generator names -* [3.1.0][cmake-3.1.0-release-notes] - * **Buggy**, see [issue #105](https://github.com/ruslo/hunter/issues/105) - * Retry download on hash mismatch ([change][cmake-retry-commit]) - * New [CMP0054][cmake-cmp0054] (best CMake policy! See [this SO question][so-cmp0054]) -* [3.2.0][cmake-3.2-release-notes] - * New synchronization command `file(LOCK ...)` ([change][cmake-file-lock-commit]) - * [HUNTER_SKIP_LOCK][error.can.not.lock] -* [3.5.0](https://cmake.org/cmake/help/v3.5/release/3.5.html#platforms) **Minimum for iOS projects** - * New variable [CMAKE_IOS_INSTALL_COMBINED](https://cmake.org/cmake/help/v3.5/variable/CMAKE_IOS_INSTALL_COMBINED.html) ([change](https://github.com/Kitware/CMake/commit/565d080a9a1e133bda868e905226181b60e90356)) - * [iOS toolchain][polly-ios-toolchain] - -### First step - -* Set [HUNTER_ROOT](https://github.com/ruslo/hunter/wiki/usr.variables#hunter_root) environment variable to an empty directory. This directory will be used by `HunterGate` module for storing packages and utility files. Using environment variable is recommended but not mandatory, see [other options][hunter-gate-effects]. - -* Set minimum CMake version: -```cmake -cmake_minimum_required(VERSION 3.0) -``` - -* Copy [gate][hunter-gate] module to your project and include it: -```cmake -include("cmake/HunterGate.cmake") -``` - -* This module will download archive automatically from `URL` that you provide to the `HUNTER_ROOT` directory (it means that there is **no** need to clone this repository in general, see [notes](https://github.com/hunter-packages/gate#notes)): - -```cmake -HunterGate( - URL "https://github.com/ruslo/hunter/archive/v0.10.9.tar.gz" - SHA1 "53b198e364dc7bc8360fc545f798563229bd7e20" -) -``` - -* Now project can be started: -```cmake -project(Foo) -``` - -* Let's download and install `boost.{regex,system,filesystem}`: -```cmake -hunter_add_package(Boost COMPONENTS regex system filesystem) -``` - -* Hunter part is done, now well known CMake-style kung-fu (see [pkg.boost](https://github.com/ruslo/hunter/wiki/pkg.boost)): -```cmake -find_package(Boost CONFIG REQUIRED regex system filesystem) - -add_executable(foo foo.cpp) -target_link_libraries(foo PUBLIC Boost::regex Boost::system Boost::filesystem) -``` - -* Summarize: -```cmake -cmake_minimum_required(VERSION 3.0) - -include("cmake/HunterGate.cmake") -HunterGate( - URL "https://github.com/ruslo/hunter/archive/v0.10.9.tar.gz" - SHA1 "53b198e364dc7bc8360fc545f798563229bd7e20" -) - -project(Foo) - -hunter_add_package(Boost COMPONENTS regex system filesystem) -find_package(Boost CONFIG REQUIRED regex system filesystem) - -add_executable(foo foo.cpp) -target_link_libraries(foo PUBLIC Boost::regex Boost::system Boost::filesystem) -``` - -* Build it: -``` -> cmake -H. -B_builds -DHUNTER_STATUS_DEBUG=ON -DCMAKE_BUILD_TYPE=Release -> cmake --build _builds --config Release -``` - -* [Tiny project with GTest][hunter-simple] - -### Usage - -* List of packages and usage instructions for each package can be found in [wiki sidebar][hunter-wiki] -* List of global control [variables][usr.variables] -* How to add a new [CMake project][usr.adding.new.package] -* How to add a new [custom-build project][usr.adding.new.package.custom.scheme] -* [Multiple HunterGate][usr.multiple.huntergate] commands (e.g. projects subprojects) - -### Hunter-ID - -First level of customization. Hunter-ID is the first 7 digits of `SHA1` of Hunter archive. I.e. each Hunter-ID contains list of projects that you can build and list of versions. Each version has it's unique `URL` and `SHA1`. Several Hunter-ID can coexists in same `HUNTER_ROOT` directory. `HunterGate` command will control your choice: - -* `1eae623` - * Hunter `0.8.3` - * `Foo 1.0.0` -> `http://mysite.com/Foo-1.0.0.tar.gz` - * `Boo 2.0.0` -> `http://mysite.com/Boo-2.0.0.tar.gz` - * `Roo 1.2.3` -> `http://mysite.com/Roo-1.2.3.tar.gz` - * -> `${HUNTER_ROOT}/_Base/1eae623/...` -* `e07a124` - * Hunter `0.8.4` - * `Awesome 1.0.0` -> `http://example.com/Awesome-1.0.0.tar.gz` - * `Best 2.0.0` -> `http://example.com/Best-2.0.0.tar.gz` - * `Foo 1.0.0` -> `http://example.com/Foo-1.0.0-patch-1.tar.gz` # yep, different URL/SHA1 - * -> `${HUNTER_ROOT}/_Base/e07a124/...` - -Message in logs: -```cmake --- [hunter] [ Hunter-ID: 1eae623 | Config-ID: ... | Toolchain-ID: ... ] --- [hunter] [ Hunter-ID: e07a124 | Config-ID: ... | Toolchain-ID: ... ] -``` - -* [Releases](https://github.com/ruslo/hunter/releases) - -### Config-ID - -Second level of customization. Config-ID is the first 7 digits of `SHA1` of the file with `hunter_config` commands (internal unified representation). This level can be customized with `HunterGate` [options][hunter-gate-custom-config]: `GLOBAL`, `LOCAL` and `FILEPATH`. Same `Hunter-ID` can be built with different versions of packages and different CMake arguments: - -* `0fa873a` - * `Foo 1.0.0` - * `Boo 2.0.0` with option `BOO_WITH_SOMETHING=YES` - * -> `${HUNTER_ROOT}/_Base/1eae623/0fa873a` -* `e9da39c` - * `Foo 2.1.0` with option `FOO_SUPER_MODE=YES` - * `Boo 3.0.0` with option `BUILD_SHARED_LIBS=ON` - * -> `${HUNTER_ROOT}/_Base/1eae623/e9da39c` - -Message in logs: -```cmake --- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: ... ] --- [hunter] [ Hunter-ID: 1eae623 | Config-ID: e9da39c | Toolchain-ID: ... ] -``` - -* [Example](https://github.com/ruslo/hunter/wiki/example.custom.config.id) - -### Toolchain-ID - -Third level of customization. Each build can be run with different toolchain. In general the result is completely different root `lib`/`include` directories. For example on Windows you can simultaniously build Visual Studio (32/64), NMake, Cygwin and MinGW projects, on Linux GCC/Clang, on Mac Xcode, Makefile, iOS. Or choose different clang tools like static analyzer/sanitizers and other platforms like Android/Raspberry Pi. Each toolchain file will be forwarded to external project so if you create toolchain with compiler `g++` and flag `-std=c++11` all dependent projects will be built by `g++ -std=c++11`. Information about toolchain has some internal representation (`toolchain.info`) and user can see first 7 digits (ID) of `SHA1` hash of this file. - -* `d46ea0b` - * `gcc` - * -> `${HUNTER_ROOT}/_Base/1eae623/0fa873a/d46ea0b` -* `c018e63` - * `clang` - * -> `${HUNTER_ROOT}/_Base/1eae623/0fa873a/c018e63` -* `c39da39` - * `clang -std=c++11` - * -> `${HUNTER_ROOT}/_Base/1eae623/0fa873a/c39da39` - -Message in logs: -``` --- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: d46ea0b ] --- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: c018e63 ] --- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: c39da39 ] -``` - -* [Collection of toolchains][polly] -* [Android example](https://github.com/forexample/android-cmake) - -### Uninstall - -All directories inside `${HUNTER_ROOT}/_Base` are reconstructible. You can remove all temps (downloads, unpacked directories, installed directories etc.) by command: -```bash -rm -rf "${HUNTER_ROOT}/_Base" -``` -or remove particular Hunter-ID by command: -```bash -rm -rf "${HUNTER_ROOT}/_Base/62422b8" # remove installed libraries -rm -rf "${HUNTER_ROOT}/_Base/Download/Hunter/0.8.3/62422b8" # remove Hunter itself -``` - -### Questions? - -Feel free to open new [issue][hunter-new-issue] if you want to ask any questions. Also you can write me to `ruslan_baratov@yahoo.com` or contact me using [Tox](https://tox.chat/): -* `7EBD836B7690C3742E6F3632742BEB00283529E06D76E06F7065544A5F9C6F37D948FB0F754B` -* `4EED21EA40B0351D8BFC85A69499A3F7CFEDA6844DA39FF1783A4D9827423F075D7194707C43` - -### Contribution - -* [Contribution](https://github.com/ruslo/hunter/wiki/dev.contribution) - -### Donations - -* [Donations](https://github.com/ruslo/hunter/blob/develop/donate.md) - -### Links -* [Gate to hunter packages][hunter-gate] -* [Simple project example][hunter-simple] -* [Bigger one](https://github.com/ruslo/weather) -* [Toolchain examples][polly] -* [Travis CI build example](https://github.com/forexample/hunter-simple/blob/master/.travis.yml) - -[travis-master]: https://travis-ci.org/ruslo/hunter.svg?branch=master -[travis-hunter]: https://travis-ci.org/ruslo/hunter/builds - -[appveyor-master]: https://ci.appveyor.com/api/projects/status/ubo6jse3lh5ciyvv/branch/master?svg=true -[appveyor-hunter]: https://ci.appveyor.com/project/ruslo/hunter/history - -[cmake-external-project]: http://www.cmake.org/cmake/help/v3.2/module/ExternalProject.html -[ios-bug]: http://public.kitware.com/Bug/view.php?id=12506 -[dry-principle]: http://c2.com/cgi/wiki?DontRepeatYourself - -[cmake-retry-commit]: https://github.com/Kitware/CMake/commit/30a94eecdb5c580d83a224848b78d186643e8105 -[cmake-file-lock-commit]: https://github.com/Kitware/CMake/commit/e6db4c5a4ede8039ed525e3facebd7e0eb7ec1b7 - -[cmake-3.0.0-release-notes]: http://www.cmake.org/cmake/help/v3.0/release/3.0.0.html#commands -[cmake-3.1.0-release-notes]: http://www.cmake.org/cmake/help/v3.1/release/3.1.0.html#syntax -[cmake-3.2-release-notes]: http://www.cmake.org/cmake/help/v3.2/release/3.2.html#commands -[cmake-cmp0054]: http://www.cmake.org/cmake/help/v3.1/policy/CMP0054.html - -[so-cmp0054]: http://stackoverflow.com/questions/19982340 - -[hunter-wiki]: https://github.com/ruslo/hunter/wiki -[usr.adding.new.package]: https://github.com/ruslo/hunter/wiki/usr.adding.new.package -[usr.variables-hunter-enabled]: https://github.com/ruslo/hunter/wiki/usr.variables#hunter_enabled -[usr.variables]: https://github.com/ruslo/hunter/wiki/usr.variables -[usr.adding.new.package.custom.scheme]: https://github.com/ruslo/hunter/wiki/usr.adding.new.package.custom.scheme -[usr.multiple.huntergate]: https://github.com/ruslo/hunter/wiki/usr.multiple.huntergate -[dev.variables-hunter-skip-lock]: https://github.com/ruslo/hunter/wiki/dev.variables#hunter_skip_lock -[error.can.not.lock]: https://github.com/ruslo/hunter/wiki/error.can.not.lock -[hunter-configuration-types]: https://github.com/ruslo/hunter/wiki/usr.variables#hunter_configuration_types - -[hunter-new-issue]: https://github.com/ruslo/hunter/issues/new - -[hunter-master-branch]: https://github.com/ruslo/hunter/tree/master -[hunter-dev-branch]: https://github.com/ruslo/hunter/tree/develop -[default-config]: https://github.com/ruslo/hunter/blob/master/cmake/configs/default.cmake -[hunter-releases]: https://github.com/ruslo/hunter/releases -[gtest-hunter]: https://github.com/ruslo/hunter/blob/master/cmake/projects/GTest/hunter.cmake -[build-schemes-dir]: https://github.com/ruslo/hunter/tree/master/cmake/schemes - -[hunter-id]: https://github.com/ruslo/hunter/tree/develop#hunter-id -[config-id]: https://github.com/ruslo/hunter/tree/develop#config-id -[toolchain-id]: https://github.com/ruslo/hunter/tree/develop#toolchain-id - -[hunter-gate]: https://github.com/hunter-packages/gate -[hunter-gate-effects]: https://github.com/hunter-packages/gate#effects -[hunter-gate-custom-config]: https://github.com/hunter-packages/gate#usage-custom-config - -[polly-ios-toolchain]: https://github.com/ruslo/polly/wiki/Toolchain-list#ios -[polly]: https://github.com/ruslo/polly -[hunter-simple]: https://github.com/forexample/hunter-simple diff --git a/README.rst b/README.rst new file mode 100644 index 0000000000..671d9c7fa4 --- /dev/null +++ b/README.rst @@ -0,0 +1,11 @@ +Hunter +====== + +* Cross-platform package manager for C++ (based on CMake [ExternalProject][cmake-external-project]) +* Supported platforms: **Linux**, **Mac**, **Windows**, **iOS**, **Android**, **Raspberry Pi** + +### CI + +* Travis CI OSX/Linux: [![Build Status][travis-master]][travis-hunter] +* AppVeyor CI Windows: [![Build Status][appveyor-master]][appveyor-hunter] +* [Per package deep testing table](https://github.com/ingenue/hunter/branches/all) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000..25f675713b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,305 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Hunter documentation build configuration file, created by +# sphinx-quickstart on Tue Mar 22 19:58:21 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +### http://stackoverflow.com/a/28778969/2288008 { +import sphinx.environment +from docutils.utils import get_source_line + +def _warn_node(self, msg, node): + if not msg.startswith('nonlocal image URI found:'): + self._warnfunc(msg, '%s:%s' % get_source_line(node)) + +sphinx.environment.BuildEnvironment.warn_node = _warn_node +### } + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Hunter' +copyright = '2016 Ruslan Baratov' +author = 'Ruslan Baratov' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.14' +# The full version, including alpha/beta/rc tags. +release = '0.14' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# From: +# * https://github.com/snide/sphinx_rtd_theme#using-this-theme-locally-then-building-on-read-the-docs +# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if not on_rtd: # only import and set the theme if we're building docs locally + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Hunterdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'Hunter.tex', 'Hunter Documentation', + 'Ruslan Baratov', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'hunter', 'Hunter Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'Hunter', 'Hunter Documentation', + author, 'Hunter', 'CMake-based cross-platform package manager for C++.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/contacts.rst b/docs/contacts.rst new file mode 100644 index 0000000000..335d43bb11 --- /dev/null +++ b/docs/contacts.rst @@ -0,0 +1,11 @@ +Contacts +-------- + +Feel free to open new `issue`_ if you want to ask any questions. Also you can +write me to ``ruslan_baratov@yahoo.com`` or contact me using `Tox`_: + +* ``7EBD836B7690C3742E6F3632742BEB00283529E06D76E06F7065544A5F9C6F37D948FB0F754B`` +* ``4EED21EA40B0351D8BFC85A69499A3F7CFEDA6844DA39FF1783A4D9827423F075D7194707C43`` + +.. _issue: https://github.com/ruslo/hunter/issues/new +.. _Tox: https://tox.chat diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000000..59d0a98e54 --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,4 @@ +Contributing +------------ + +* `Contribution `_ diff --git a/docs/creating-new.rst b/docs/creating-new.rst new file mode 100644 index 0000000000..52323d0974 --- /dev/null +++ b/docs/creating-new.rst @@ -0,0 +1,16 @@ +Creating new package +-------------------- + +.. _creating new: + +This is a guide for adding new package to Hunter. We start with the simple +one (CMake based, no dependencies), then cover "hunterization" (CMake based, +depends on other packages). Final is a most complex one (non-CMake packages, +creating custom build scheme). + +.. toctree:: + :maxdepth: 1 + + /creating-new/cmake + /creating-new/cmake-dependencies + /creating-new/custom diff --git a/docs/creating-new/cmake-dependencies.rst b/docs/creating-new/cmake-dependencies.rst new file mode 100644 index 0000000000..02545693bc --- /dev/null +++ b/docs/creating-new/cmake-dependencies.rst @@ -0,0 +1,2 @@ +CMake (with dependencies) +------------------------- diff --git a/docs/creating-new/cmake.rst b/docs/creating-new/cmake.rst new file mode 100644 index 0000000000..44ba3e4a57 --- /dev/null +++ b/docs/creating-new/cmake.rst @@ -0,0 +1,6 @@ +CMake (no dependencies) +----------------------- + +* How to add a new `CMake project`_ + +.. _CMake project: https://github.com/ruslo/hunter/wiki/usr.adding.new.package diff --git a/docs/creating-new/custom.rst b/docs/creating-new/custom.rst new file mode 100644 index 0000000000..45596ccc40 --- /dev/null +++ b/docs/creating-new/custom.rst @@ -0,0 +1,6 @@ +Non-CMake: custom scheme +------------------------ + +* How to add a new `custom-build project`_ + +.. _custom-build project: https://github.com/ruslo/hunter/wiki/usr.adding.new.package.custom.scheme diff --git a/docs/donations.rst b/docs/donations.rst new file mode 100644 index 0000000000..a5cb0892e4 --- /dev/null +++ b/docs/donations.rst @@ -0,0 +1,4 @@ +Donations +--------- + +* `Donations `_ diff --git a/docs/faq.rst b/docs/faq.rst new file mode 100644 index 0000000000..581e616500 --- /dev/null +++ b/docs/faq.rst @@ -0,0 +1,2 @@ +FAQ +--- diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000..fe2d7e48d1 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,55 @@ +Hunter: organize freedom +======================== + +Welcome to the Hunter package manager documentation! + +Hunter is CMake-driven cross-platform package manager for C++ [1]_ projects. +Using Hunter you can organize builds for **Linux**, **OS X**, **Windows**, +**iOS**, **Android**, **Raspberry Pi**. Third party external projects are highly +customizable (versions, CMake ``-D`` build options, Release/Debug, +static/shared). Variants can be picked from global defaults or controlled by +your local CMake code. Separate root directory will be created for each variant +so all variants can be used simultaneously on one machine without conflicts +(just like `virtualenv`_ but automatically). Going further: each such root +directory can be shared between several local projects if configuration of +externals matches. So when you are staring project from scratch and use same +external packages there will be no additional copying or builds triggered, the +only overhead is checking existence of one ``DONE`` stamp file for each +package. In case your local environment is similar enough to continious +integration environment of Travis/AppVeyor then build will not be triggered at +all - cached binaries will be downloaded instead. Mainly Hunter designed to +manage packages with CMake build system under the hood - existing CMake package +can be quite easily integrated into system but non-CMake packages supported too +using custom templates (build schemes) with ``ExternalProject_Add`` command(s). +Client is a collection of CMake only modules so it supports from the box all +platforms/generators/IDEs which CMake can handle like Visual Studio, Xcode, +QtCreator, NMake, Ninja, Cygwin or MinGW. Works fine with CMake-GUI too. + +Prime directive used to add package to the current root is +``hunter_add_package`` which companioning CMake's ``find_package``. For +example: + +.. code-block:: cmake + + hunter_add_package(Boost COMPONENTS system filesystem iostreams) + find_package(Boost COMPONENTS system filesystem iostreams) + +Sounds interesting? Keep reading! + +.. toctree:: + :maxdepth: 1 + + /overview + /quick-start + /user-guides + List of packages + /creating-new + Frequently Asked Questions + /contributing + /contacts + /donations + /reference + +.. [1] C++ is the main goal, works for other types as well. See :ref:`Manage anything `. + +.. _virtualenv: https://virtualenv.pypa.io/en/latest/ diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 0000000000..7727306207 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,20 @@ +Brief overview +-------------- + +This is a brief overview of big picture. It takes about 5 minutes of reading +but will show you the main features/aspects of using Hunter. Avoid running +real code for now, it will be covered in next :ref:`Quick start ` section. + +.. toctree:: + :maxdepth: 1 + + /overview/what-is-it + /overview/automatic + /overview/dry + /overview/customization + /overview/shareable + /overview/binaries + /overview/anything + /overview/compatibility + /overview/cmake-only + /overview/everywhere diff --git a/docs/overview/anything.rst b/docs/overview/anything.rst new file mode 100644 index 0000000000..4d99775f06 --- /dev/null +++ b/docs/overview/anything.rst @@ -0,0 +1,12 @@ +Manage anything +--------------- + +.. _manage-anything: + +You can manage anything that can be downloaded by ``URL`` and checked with +``SHA1`` hash: + +* C++ packages +* CMake modules +* Additional sources +* Resources (pictures, data for testing, ...) diff --git a/docs/overview/automatic.rst b/docs/overview/automatic.rst new file mode 100644 index 0000000000..27ee435bbf --- /dev/null +++ b/docs/overview/automatic.rst @@ -0,0 +1,55 @@ +Automatic builds +---------------- + +Build instructions from Hunter archive triggered automatically when +``hunter_add_package`` function called. Hence there is no need to specify +dependencies in a raw ``README`` file like: + +:: + + For OSX please do: + > brew install foo boo + + For Ubuntu please do: + > sudo apt-get install foo boo + + Then run build: + > cmake -H. -B_builds + > cmake --build _builds + +Now it's simply: + +:: + + Just run build: + > cmake -H. -B_builds # dependencies installed automatically + > cmake --build _builds + +Optional dependency? No problems, expressed in a pretty clean way: + +.. code-block:: cmake + + # required dependencies + hunter_add_package(foo) + hunter_add_package(boo) + if(BUILD_WITH_BAR) + hunter_add_package(bar) + endif() + +Same commands: + +:: + + > cmake -H. -B_builds -DBUILD_WITH_BAR=YES # + install bar + +instead of: + +:: + + Additionally if you want bar support please run: + > brew install bar # OSX + > sudo apt-get install bar # Ubuntu + + Then run build: + > cmake -H. -B_builds -DBUILD_WITH_BAR=YES + diff --git a/docs/overview/binaries.rst b/docs/overview/binaries.rst new file mode 100644 index 0000000000..66b34522fe --- /dev/null +++ b/docs/overview/binaries.rst @@ -0,0 +1,15 @@ +Binaries from server +-------------------- + +Hunter has internal mechanism of saving binaries of installed packages along +with meta information about toolchain, build options and dependencies. +This allow to not trigger same build on creation of new root directory. +For example when user change version of ``OpenSSL`` from ``1.0.1`` to ``1.0.2`` +it does affect ``Config-ID`` so new root will be created. But it will not affect +how ``GTest`` builds (if it's not a dependency) so ``GTest`` archive can be +unpacked from cache. Such cache can be used locally or uploaded to server. + +.. seealso:: + + * `Uploading binaries to server `_ + * `Status of uploading packages from Travis/AppVeyor `_ diff --git a/docs/overview/cmake-only.rst b/docs/overview/cmake-only.rst new file mode 100644 index 0000000000..9c7087de59 --- /dev/null +++ b/docs/overview/cmake-only.rst @@ -0,0 +1,5 @@ +CMake only +---------- + +No other dependencies - **just CMake** and your environment/IDE (no need for +Git or Python or anything). diff --git a/docs/overview/compatibility.rst b/docs/overview/compatibility.rst new file mode 100644 index 0000000000..2c699d3d60 --- /dev/null +++ b/docs/overview/compatibility.rst @@ -0,0 +1,9 @@ +Compatibility +------------- + +Backward compatibility. + +Turn Hunter off by adding one option `HUNTER_ENABLED=OFF`_ to use your old +settings. + +.. _HUNTER_ENABLED=OFF: https://github.com/ruslo/hunter/wiki/usr.variables#hunter_enabled diff --git a/docs/overview/customization.rst b/docs/overview/customization.rst new file mode 100644 index 0000000000..b1fca736d3 --- /dev/null +++ b/docs/overview/customization.rst @@ -0,0 +1,14 @@ +Customization +------------- + +You got full control of how packages will be built. You can create your own +mapping ``version`` -> ``URL``, add globals like compiler and flags or add +new build option to external package. + +.. toctree:: + :maxdepth: 1 + + Hunter-ID + Config-ID + Toolchain-ID + Build types diff --git a/docs/overview/customization/build-types.rst b/docs/overview/customization/build-types.rst new file mode 100644 index 0000000000..ea1db73560 --- /dev/null +++ b/docs/overview/customization/build-types.rst @@ -0,0 +1,4 @@ +Build types +----------- + +* `Build types like Release/Debug `_ diff --git a/docs/overview/customization/config-id.rst b/docs/overview/customization/config-id.rst new file mode 100644 index 0000000000..17367d4649 --- /dev/null +++ b/docs/overview/customization/config-id.rst @@ -0,0 +1,51 @@ +Config-ID +--------- + +.. _config-id: + +Second level of customization. Set version of package to build and build +options. + +``Config-ID`` is the first 7 digits of ``SHA1`` of the file with +``hunter_config`` commands (internal unified representation). This level can +be customized with `HunterGate options`_: ``GLOBAL``, ``LOCAL`` and +``FILEPATH``. Packages from ``Hunter-ID 1eae623`` can be built using different +versions and different CMake arguments: + ++-------------------+ +| Hunter-ID 1eae623 | ++-------------------+ + ++-------------+----------------------------------------------------------------------+ +| Config-ID | | ++=============+===================+==================================================+ +| ``0fa873a`` | Working directory | ``${HUNTER_ROOT}/_Base/1eae623/0fa873a/...`` | +| +-------------------+---------+-----------+----------------------------+ +| | Packages | Name | Version | Options | +| | +---------+-----------+----------------------------+ +| | | ``Foo`` | ``1.0.0`` | | +| | +---------+-----------+----------------------------+ +| | | ``Boo`` | ``2.0.0`` | ``BOO_WITH_SOMETHING=YES`` | ++-------------+-------------------+---------+-----------+----------------------------+ +| ``e9da39c`` | Working directory | ``${HUNTER_ROOT}/_Base/1eae623/e9da39c/...`` | +| +-------------------+---------+-----------+----------------------------+ +| | Packages | Name | Version | Options | +| | +---------+-----------+----------------------------+ +| | | ``Foo`` | ``2.1.0`` | ``FOO_SUPER_MODE=YES`` | +| | +---------+-----------+----------------------------+ +| | | ``Boo`` | ``3.0.0`` | ``BUILD_SHARED_LIBS=ON`` | ++-------------+-------------------+---------+-----------+----------------------------+ + + +Message in logs: + +:: + + -- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: ... ] + -- [hunter] [ Hunter-ID: 1eae623 | Config-ID: e9da39c | Toolchain-ID: ... ] + +.. seealso:: + + * `Example `_ + +.. _HunterGate options: https://github.com/hunter-packages/gate#usage-custom-config diff --git a/docs/overview/customization/hunter-id.rst b/docs/overview/customization/hunter-id.rst new file mode 100644 index 0000000000..07ec1de743 --- /dev/null +++ b/docs/overview/customization/hunter-id.rst @@ -0,0 +1,57 @@ +Hunter-ID +--------- + +First level of customization. Hunter archive. + +``Hunter-ID`` is the first 7 digits of ``SHA1`` +of Hunter archive. This level defines list of available packages and mapping +``version -> URL/SHA1``. Several ``Hunter-ID`` can coexists in same +``HUNTER_ROOT`` directory. ``HunterGate`` command will control your choice: + ++-------------+----------------------------------------------------------------------------------------+ +| Hunter-ID | | ++=============+===================+====================================================================+ +| ``1eae623`` | Hunter version | ``0.8.3`` | +| +-------------------+--------------------------------------------------------------------+ +| | SHA1 of archive | ``1eae623cb5ce9da39c8c3e1b0f6e452f244ddc17`` | +| +-------------------+--------------------------------------------------------------------+ +| | Working directory | ``${HUNTER_ROOT}/_Base/1eae623/...`` | +| +-------------------+--------------+-------------+---------------------------------------+ +| | Packages | ``Foo`` [1]_ | ``1.0.0`` | ``mysite.xyz/Foo-1.0.0.tar.gz`` | +| | +--------------+-------------+---------------------------------------+ +| | | ``Boo`` | ``2.0.0`` | ``mysite.xyz/Boo-2.0.0.tar.gz`` | +| | | +-------------+---------------------------------------+ +| | | | ``2.1.0`` | ``mysite.xyz/Boo-2.1.0.tar.gz`` | +| | +--------------+-------------+---------------------------------------+ +| | | ``Roo`` | ``1.2.3`` | ``mysite.xyz/Roo-1.2.3.tar.gz`` | +| | | +-------------+---------------------------------------+ +| | | | ``1.2.4`` | ``mysite.xyz/Roo-1.2.4.tar.gz`` | ++-------------+-------------------+--------------+-------------+---------------------------------------+ +| ``e07a124`` | Hunter version | ``0.8.4`` | +| +-------------------+--------------------------------------------------------------------+ +| | SHA1 of archive | ``e07a124192b0a47b0b60ade40fa873a42ec27822`` | +| +-------------------+--------------------------------------------------------------------+ +| | Working directory | ``${HUNTER_ROOT}/_Base/e07a124/...`` | +| +-------------------+--------------+----------+------------------------------------------+ +| | Packages | ``Awesome`` | ``1.0.0``| ``example.com/Awesome-1.0.0.tar.gz`` | +| | +--------------+----------+------------------------------------------+ +| | | ``Best`` | ``2.0.0``| ``example.com/Best-2.0.0.tar.gz`` | +| | | +----------+------------------------------------------+ +| | | | ``2.0.1``| ``example.com/Best-2.0.1.tar.gz`` | +| | +--------------+----------+------------------------------------------+ +| | | ``Foo`` [1]_ | ``1.0.0``| ``example.com/Foo-1.0.0-patch-1.tar.gz`` | ++-------------+-------------------+--------------+----------+------------------------------------------+ + + +.. [1] Yep, same version but different URL/SHA1. No conficts. + +Message in logs: + +:: + + -- [hunter] [ Hunter-ID: 1eae623 | Config-ID: ... | Toolchain-ID: ... ] + -- [hunter] [ Hunter-ID: e07a124 | Config-ID: ... | Toolchain-ID: ... ] + +.. seealso:: + + * `Releases `_ diff --git a/docs/overview/customization/toolchain-id.rst b/docs/overview/customization/toolchain-id.rst new file mode 100644 index 0000000000..1c70452687 --- /dev/null +++ b/docs/overview/customization/toolchain-id.rst @@ -0,0 +1,57 @@ +Toolchain-ID +------------ + +Third level of customization. Compiler and flags. + +Each build can be run with different toolchains. In general the result is +completely different root ``lib``/``include`` directories. For example on +Windows you can simultaniously build Visual Studio (32/64), NMake, Cygwin and +MinGW projects, on Linux GCC/Clang, on Mac Xcode, Makefile, iOS. Or choose +various clang tools like static analyzer/sanitizers and other platforms like +Android/Raspberry Pi. Each toolchain file will be forwarded to external project +so if you create toolchain with compiler ``g++`` and flag ``-std=c++11`` all +dependent projects will be built by ``g++ -std=c++11``. Information about +toolchain has some internal representation (``toolchain.info``) and user can +see first 7 digits (ID) of ``SHA1`` hash of this file. + ++-------------------+-------------------+ +| Hunter-ID 1eae623 | Config-ID 0fa873a | ++-------------------+-------------------+ + ++--------------+--------------------------------------------------------------------------+ +| Toolchain-ID | | ++==============+===================+======================================================+ +| ``d46ea0b`` | Working directory | ``${HUNTER_ROOT}/_Base/1eae623/0fa873a/d46ea0b/...`` | +| +-------------------+-----------+----------------+-------------------------+ +| | | Compiler | Flags | | +| +-------------------+-----------+----------------+-------------------------+ +| | | ``gcc`` | | | ++--------------+-------------------+-----------+----------------+-------------------------+ +| ``c018e63`` | Working directory | ``${HUNTER_ROOT}/_Base/1eae623/0fa873a/c018e63/...`` | +| +-------------------+-----------+----------------+-------------------------+ +| | | Compiler | Flags | | +| +-------------------+-----------+----------------+-------------------------+ +| | | ``clang`` | | | ++--------------+-------------------+-----------+----------------+-------------------------+ +| ``c39da39`` | Working directory | ``${HUNTER_ROOT}/_Base/1eae623/0fa873a/c39da39/...`` | +| +-------------------+-----------+----------------+-------------------------+ +| | | Compiler | Flags | | +| +-------------------+-----------+----------------+-------------------------+ +| | | ``clang`` | ``-std=c++11`` | | ++--------------+-------------------+-----------+----------------+-------------------------+ + + +Message in logs: + +:: + + -- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: d46ea0b ] + -- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: c018e63 ] + -- [hunter] [ Hunter-ID: 1eae623 | Config-ID: 0fa873a | Toolchain-ID: c39da39 ] + +.. seealso:: + + * `Collection of toolchains `_ + * `Android example `_ + + diff --git a/docs/overview/dry.rst b/docs/overview/dry.rst new file mode 100644 index 0000000000..80a6ae1e97 --- /dev/null +++ b/docs/overview/dry.rst @@ -0,0 +1,22 @@ +Don't Repeat Yourself +--------------------- + +If you already familiar with `ExternalProject_Add`_ and have wrote some +super-build projects before you probably already awared that writing complete +solution with toolchains, build types, build options, parallel jobs, +forwarding of compiler flags and making it works correctly for all generators +is not a trivial task. + +Hunter store `ExternalProject_Add`_ recipies as a collection of templates. Once +written formula (`build scheme`_) can be reused by other projects without +copying of collection of superbuild files (`DRY principle`_). +When new package with new scheme introduced all you need to do is just update +``SHA1``/``URL`` of ``HunterGate`` command. + +.. seealso:: + + * `How to use CMake ExternalProject_Add or alternatives in a cross platform way? `_ + +.. _ExternalProject_Add: http://www.cmake.org/cmake/help/v3.2/module/ExternalProject.html +.. _build scheme: https://github.com/ruslo/hunter/tree/master/cmake/schemes +.. _DRY principle: http://c2.com/cgi/wiki?DontRepeatYourself diff --git a/docs/overview/everywhere.rst b/docs/overview/everywhere.rst new file mode 100644 index 0000000000..2b985fe6e6 --- /dev/null +++ b/docs/overview/everywhere.rst @@ -0,0 +1,5 @@ +Works everywhere! +----------------- + +Hunter works everywhere: CMake-GUI, Qt Creator, Visual Studio, Xcode, Cygwin, +MinGW, Jenkins, Travis etc. diff --git a/docs/overview/shareable.rst b/docs/overview/shareable.rst new file mode 100644 index 0000000000..26e44d4c9d --- /dev/null +++ b/docs/overview/shareable.rst @@ -0,0 +1,16 @@ +Shareable +--------- + +Root directory with installed packages can be shared between several local +projects. In case if one local project trigger installing of some new third +party package then root directory will be locked for modifications until install +finished or interrupted. Other local project that will try to run +``hunter_add_package`` in same root will be automatically paused and spin +waiting for unlock. Note that different root directories do different locks, +e.g. triggering build of ``OpenSSL`` for ``iOS`` will not pause building of +``GTest`` for ``Android``. Internally this is done by ``file(LOCK ...)`` CMake +command (available since ``3.2``). + +Same synchronization done for the initializing Hunter by ``HunterGate`` command. +This is very handy feature for the CI systems with envoronment which is shared +between several jobs, e.g. Jenkins. diff --git a/docs/overview/what-is-it.rst b/docs/overview/what-is-it.rst new file mode 100644 index 0000000000..fcfc9459f1 --- /dev/null +++ b/docs/overview/what-is-it.rst @@ -0,0 +1,88 @@ +What is it? +----------- + +Every Hunter `release`_ (`Atom feed`_) archive is a meta-package with build +instructions and URLs of real packages. Archive will be downloaded and +unpacked automatically by ``HunterGate`` CMake module. You only need to set +``URL`` and ``SHA1``: + +.. code-block:: cmake + + HunterGate( + URL "https://github.com/ruslo/hunter/archive/v0.14.5.tar.gz" + SHA1 "f2c3de6d13baf8c5d2aa77bdc47c516e668c677e" + ) + +Here is content of the archive in simplified form: + +.. code-block:: none + + Hunter (0.14.15) = { + Boost (1.60.0, 1.59.0, 1.58.0-p1, ...), + GTest (1.7.0, ...), + OpenCV (3.0.0-beta, 2.4.11, 2.4.10, ...), + OpenSSL (1.0.2g, 1.0.2f, 1.0.2e, ...), + ... + } + +If you download and unpack it you can view some internals. Let's see OpenSSL +package properties: + +.. literalinclude:: what-is-it.sh + :language: shell + :start-after: # doc: download-start + :end-before: # doc: download-end + +`hunter.cmake`_ holds list of available versions: + +.. literalinclude:: what-is-it.sh + :language: shell + :start-after: # doc: version-start + :end-before: # doc: version-end + +.. code-block:: shell + + VERSION + "1.0.2g" + URL + "https://github.com/openssl/openssl/archive/OpenSSL_1_0_2g.tar.gz" + -- + VERSION + "1.0.2f" + URL + "https://github.com/openssl/openssl/archive/OpenSSL_1_0_2f.tar.gz" + -- + VERSION + "1.0.2e" + URL + "https://github.com/openssl/openssl/archive/OpenSSL_1_0_2e.tar.gz" + +Install instructions from build scheme `url_sha1_openssl.cmake.in`_: + +.. literalinclude:: what-is-it.sh + :language: shell + :start-after: # doc: install-start + :end-before: # doc: install-end + +.. code-block:: cmake + + INSTALL_COMMAND + make install_sw + +Default version from `default.cmake`_ +(is customizable, see :ref:`Config-ID `): + +.. literalinclude:: what-is-it.sh + :language: shell + :start-after: # doc: default-start + :end-before: # doc: default-stop + +.. code-block:: cmake + + hunter_config(OpenSSL VERSION 1.0.2g) + +.. _release: https://github.com/ruslo/hunter/releases +.. _Atom feed: https://github.com/ruslo/hunter/releases.atom +.. _default.cmake: https://github.com/ruslo/hunter/blob/master/cmake/configs/default.cmake +.. _hunter.cmake: https://github.com/ruslo/hunter/blob/master/cmake/projects/OpenSSL/hunter.cmake +.. _url_sha1_openssl.cmake.in: https://github.com/ruslo/hunter/blob/master/cmake/projects/OpenSSL/schemes/url_sha1_openssl.cmake.in diff --git a/docs/overview/what-is-it.sh b/docs/overview/what-is-it.sh new file mode 100755 index 0000000000..1c81c924d8 --- /dev/null +++ b/docs/overview/what-is-it.sh @@ -0,0 +1,24 @@ +#!/bin/bash -e + +rm -f v0.14.5.tar.gz +rm -rf hunter-0.14.5 + +# doc: download-start +wget https://github.com/ruslo/hunter/archive/v0.14.5.tar.gz +tar xf v0.14.5.tar.gz +# doc: download-end + +# doc: version-start +grep -A3 -m3 VERSION hunter-0.14.5/cmake/projects/OpenSSL/hunter.cmake +# doc: version-end + +# doc: install-start +grep -A1 INSTALL_COMMAND hunter-0.14.5/cmake/projects/OpenSSL/schemes/url_sha1_openssl.cmake.in +# doc: install-end + +# doc: default-start +grep '\' -m1 hunter-0.14.5/cmake/configs/default.cmake +# doc: default-stop + +rm -f v0.14.5.tar.gz +rm -rf hunter-0.14.5 diff --git a/docs/packages.rst b/docs/packages.rst new file mode 100644 index 0000000000..6bf99a8933 --- /dev/null +++ b/docs/packages.rst @@ -0,0 +1,11 @@ +Packages +-------- + +List of packages and usage instructions for each package can be found in `wiki sidebar`_. + +.. toctree:: + :maxdepth: 1 + + /packages/all-packages.rst + +.. _wiki sidebar: https://github.com/ruslo/hunter/wiki diff --git a/docs/packages/all-packages.rst b/docs/packages/all-packages.rst new file mode 100644 index 0000000000..3cdeb7a46c --- /dev/null +++ b/docs/packages/all-packages.rst @@ -0,0 +1,2 @@ +All packages +------------ diff --git a/docs/quick-start.rst b/docs/quick-start.rst new file mode 100644 index 0000000000..637384471d --- /dev/null +++ b/docs/quick-start.rst @@ -0,0 +1,22 @@ +Quick start +----------- + +.. _quick-start: + +Short description of main commands. First part is about choosing CMake version +to use, then example of commands for downloading Boost components. At the end +take a look at GitHub repository with tiny project that use GTest and try it +yourself. + +.. toctree:: + :maxdepth: 1 + + CMake version + /quick-start/boost-components + /quick-start/simple + /quick-start/uninstall + +.. seealso:: + + * `HunterGate `_ + * `Weather `_ diff --git a/docs/quick-start/boost-components.rst b/docs/quick-start/boost-components.rst new file mode 100644 index 0000000000..84b456d1a2 --- /dev/null +++ b/docs/quick-start/boost-components.rst @@ -0,0 +1,84 @@ +First step +---------- + +Set `HUNTER_ROOT`_ environment variable to **an empty directory**. This +directory will be used by ``HunterGate`` module for storing packages and +utility files. Using environment variable is recommended but not mandatory, +see `other options`_. + +Set minimum CMake version: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + +Copy `HunterGate`_ module to your project and include it: + +.. code-block:: cmake + + include("cmake/HunterGate.cmake") + +This module will download archive automatically from ``URL`` that you provide +to the ``HUNTER_ROOT`` directory (it means that there is **no need to clone +this repository** in general, see `notes`_): + +.. code-block:: cmake + + HunterGate( + URL "https://github.com/ruslo/hunter/archive/v0.10.9.tar.gz" + SHA1 "53b198e364dc7bc8360fc545f798563229bd7e20" + ) + +Now project can be started: + +.. code-block:: cmake + + project(Foo) + +Let's download and install ``boost.{regex,system,filesystem}``: + +.. code-block:: cmake + + hunter_add_package(Boost COMPONENTS regex system filesystem) + +Hunter part is done, now well known CMake-style kung-fu (see `pkg.boost`_): + +.. code-block:: cmake + + find_package(Boost CONFIG REQUIRED regex system filesystem) + + add_executable(foo foo.cpp) + target_link_libraries(foo PUBLIC Boost::regex Boost::system Boost::filesystem) + +Summarize: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + + include("cmake/HunterGate.cmake") + HunterGate( + URL "https://github.com/ruslo/hunter/archive/v0.10.9.tar.gz" + SHA1 "53b198e364dc7bc8360fc545f798563229bd7e20" + ) + + project(Foo) + + hunter_add_package(Boost COMPONENTS regex system filesystem) + find_package(Boost CONFIG REQUIRED regex system filesystem) + + add_executable(foo foo.cpp) + target_link_libraries(foo PUBLIC Boost::regex Boost::system Boost::filesystem) + +Build it: + +.. code-block:: shell + + > cmake -H. -B_builds -DHUNTER_STATUS_DEBUG=ON -DCMAKE_BUILD_TYPE=Release + > cmake --build _builds --config Release + +.. _HUNTER_ROOT: https://github.com/ruslo/hunter/wiki/usr.variables#hunter_root +.. _other options: https://github.com/hunter-packages/gate#effects +.. _HunterGate: https://github.com/hunter-packages/gate +.. _notes: https://github.com/hunter-packages/gate#notes +.. _pkg.boost: https://github.com/ruslo/hunter/wiki/pkg.boost diff --git a/docs/quick-start/cmake.rst b/docs/quick-start/cmake.rst new file mode 100644 index 0000000000..b9e9f2fb24 --- /dev/null +++ b/docs/quick-start/cmake.rst @@ -0,0 +1,42 @@ +Notes about version of CMake +---------------------------- + +* `3.0.0`_ **Minimum required** + + * **Buggy**, see `PR #198`_ + * Interface header-only libraries + * Sub-option ``VERSION`` for command ``project`` + * New MSVC generator names + +* `3.1.0`_ + + * **Buggy**, see `issue #105`_ + * Retry download on hash mismatch (`change `__) + * New `CMP0054`_ (best CMake policy!) See `this SO question`_ + +* `3.2.0`_ + + * New synchronization command ``file(LOCK ...)`` (`change `__) + * `HUNTER_SKIP_LOCK`_ + +* `3.5.0`_ **Minimum for iOS projects** + + * New variable `CMAKE_IOS_INSTALL_COMBINED`_ (`change `__) + * `iOS toolchains`_ + +.. _3.0.0: http://www.cmake.org/cmake/help/v3.0/release/3.0.0.html#commands +.. _3.1.0: http://www.cmake.org/cmake/help/v3.1/release/3.1.0.html#syntax +.. _3.2.0: http://www.cmake.org/cmake/help/v3.2/release/3.2.html#commands +.. _3.5.0: https://cmake.org/cmake/help/v3.5/release/3.5.html#platforms + +.. _CMP0054: http://www.cmake.org/cmake/help/v3.1/policy/CMP0054.html + +.. _PR #198: https://github.com/ruslo/hunter/pull/198#issuecomment-120630877 +.. _issue #105: https://github.com/ruslo/hunter/issues/105 + +.. _this SO question: http://stackoverflow.com/questions/19982340 + +.. _HUNTER_SKIP_LOCK: https://github.com/ruslo/hunter/wiki/error.can.not.lock +.. _CMAKE_IOS_INSTALL_COMBINED: https://cmake.org/cmake/help/v3.5/variable/CMAKE_IOS_INSTALL_COMBINED.html + +.. _iOS toolchains: https://github.com/ruslo/polly/wiki/Toolchain-list#ios diff --git a/docs/quick-start/simple.rst b/docs/quick-start/simple.rst new file mode 100644 index 0000000000..761fa7ddd1 --- /dev/null +++ b/docs/quick-start/simple.rst @@ -0,0 +1,4 @@ +Simple example +-------------- + +* `Tiny project with GTest `_ diff --git a/docs/quick-start/uninstall.rst b/docs/quick-start/uninstall.rst new file mode 100644 index 0000000000..29fdaec913 --- /dev/null +++ b/docs/quick-start/uninstall.rst @@ -0,0 +1,17 @@ +Uninstall +--------- + +All directories inside ``${HUNTER_ROOT}/_Base`` are reconstructible. You can +remove all temps (downloads, unpacked directories, installed directories etc.) +by command: + +.. code-block:: shell + + rm -rf "${HUNTER_ROOT}/_Base" + +or remove particular ``Hunter-ID`` by command: + +.. code-block:: shell + + rm -rf "${HUNTER_ROOT}/_Base/62422b8" # remove installed libraries + rm -rf "${HUNTER_ROOT}/_Base/Download/Hunter/0.8.3/62422b8" # remove Hunter itself diff --git a/docs/reference.rst b/docs/reference.rst new file mode 100644 index 0000000000..68696dc638 --- /dev/null +++ b/docs/reference.rst @@ -0,0 +1,12 @@ +Reference +--------- + +.. toctree:: + :maxdepth: 1 + + /reference/terminology + /reference/errors + /reference/user-variables + /reference/user-modules + /reference/internal-variables + /reference/internal-modules diff --git a/docs/reference/errors.rst b/docs/reference/errors.rst new file mode 100644 index 0000000000..2da32de46b --- /dev/null +++ b/docs/reference/errors.rst @@ -0,0 +1,2 @@ +Errors +------ diff --git a/docs/reference/internal-modules.rst b/docs/reference/internal-modules.rst new file mode 100644 index 0000000000..f01128ed5d --- /dev/null +++ b/docs/reference/internal-modules.rst @@ -0,0 +1,2 @@ +Internal modules +---------------- diff --git a/docs/reference/internal-variables.rst b/docs/reference/internal-variables.rst new file mode 100644 index 0000000000..6d190ca536 --- /dev/null +++ b/docs/reference/internal-variables.rst @@ -0,0 +1,2 @@ +Internal variables +------------------ diff --git a/docs/reference/terminology.rst b/docs/reference/terminology.rst new file mode 100644 index 0000000000..4717fdef5c --- /dev/null +++ b/docs/reference/terminology.rst @@ -0,0 +1,6 @@ +Terminology +----------- + +* CMake cache +* Hunter cache +* Binary cache server diff --git a/docs/reference/user-modules.rst b/docs/reference/user-modules.rst new file mode 100644 index 0000000000..c31ce241dc --- /dev/null +++ b/docs/reference/user-modules.rst @@ -0,0 +1,2 @@ +User modules +------------ diff --git a/docs/reference/user-variables.rst b/docs/reference/user-variables.rst new file mode 100644 index 0000000000..f41bb19867 --- /dev/null +++ b/docs/reference/user-variables.rst @@ -0,0 +1,4 @@ +User variables +-------------- + +* List of global control `variables `_ diff --git a/docs/user-guides.rst b/docs/user-guides.rst new file mode 100644 index 0000000000..2d041d92f7 --- /dev/null +++ b/docs/user-guides.rst @@ -0,0 +1,13 @@ +User guides +----------- + +Guides splitted into sections by role of developer in project. Sections should +be read sequentinally one by one. + +.. toctree:: + :maxdepth: 1 + + /user-guides/regular + /user-guides/cmake-user + /user-guides/hunter-user + /user-guides/hunter-developer diff --git a/docs/user-guides/cmake-user.rst b/docs/user-guides/cmake-user.rst new file mode 100644 index 0000000000..b2260b5664 --- /dev/null +++ b/docs/user-guides/cmake-user.rst @@ -0,0 +1,9 @@ +CMake user +---------- + +This is quite the same as C++ developer. + +* do not add dependencies +* no c++flags (only warnings) +* add more sources +* add more targets diff --git a/docs/user-guides/hunter-developer.rst b/docs/user-guides/hunter-developer.rst new file mode 100644 index 0000000000..62d9f366fc --- /dev/null +++ b/docs/user-guides/hunter-developer.rst @@ -0,0 +1,5 @@ +Hunter developer +---------------- + +* reference to modules +* layout guide diff --git a/docs/user-guides/hunter-user.rst b/docs/user-guides/hunter-user.rst new file mode 100644 index 0000000000..1fbd303fc1 --- /dev/null +++ b/docs/user-guides/hunter-user.rst @@ -0,0 +1,9 @@ +Hunter user +----------- + +* add more find_packages +* add toolchain-id flags +* add hunter_add_package +* custom configs +* add package +* -> CGold diff --git a/docs/user-guides/regular.rst b/docs/user-guides/regular.rst new file mode 100644 index 0000000000..78ae151074 --- /dev/null +++ b/docs/user-guides/regular.rst @@ -0,0 +1,2 @@ +Regular user +------------