Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update commands help for v2 #2999

Merged
merged 5 commits into from
Feb 21, 2023
Merged

Update commands help for v2 #2999

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ce06588
Update --help codeblocks to latest version
AbrilRBS Feb 20, 2023
7f9ca5d
Sync review changes
AbrilRBS Feb 20, 2023
55ac34a
Add missing newline
AbrilRBS Feb 20, 2023
277f7eb
fixed
franramirez688 Feb 21, 2023
3a47d72
changed bash to text
franramirez688 Feb 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 76 additions & 30 deletions reference/commands/build.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,70 +5,116 @@ conan build

.. code-block:: text

$ conan build --help
usage: conan build [-h] [-v [V]] [--logger] [--name NAME] [--version VERSION] [--user USER] [--channel CHANNEL] [-of OUTPUT_FOLDER] [-b BUILD] [-r REMOTE | -nr] [-u] [-o OPTIONS_HOST] [-o:b OPTIONS_BUILD] [-o:h OPTIONS_HOST]
[-pr PROFILE_HOST] [-pr:b PROFILE_BUILD] [-pr:h PROFILE_HOST] [-s SETTINGS_HOST] [-s:b SETTINGS_BUILD] [-s:h SETTINGS_HOST] [-c CONF_HOST] [-c:b CONF_BUILD] [-c:h CONF_HOST] [-l LOCKFILE] [--lockfile-partial]
[--lockfile-out LOCKFILE_OUT] [--lockfile-packages] [--lockfile-clean]
$ conan build -h
usage: conan build [-h] [-v [V]] [--logger] [--name NAME] [--version VERSION]
[--user USER] [--channel CHANNEL] [-of OUTPUT_FOLDER]
[-b BUILD] [-r REMOTE | -nr] [-u] [-o OPTIONS_HOST]
[-o:b OPTIONS_BUILD] [-o:h OPTIONS_HOST] [-pr PROFILE_HOST]
[-pr:b PROFILE_BUILD] [-pr:h PROFILE_HOST]
[-s SETTINGS_HOST] [-s:b SETTINGS_BUILD]
[-s:h SETTINGS_HOST] [-c CONF_HOST] [-c:b CONF_BUILD]
[-c:h CONF_HOST] [-l LOCKFILE] [--lockfile-partial]
[--lockfile-out LOCKFILE_OUT] [--lockfile-packages]
[--lockfile-clean]
[path]

Install + calls the build() method
Install dependencies and call the build() method.

positional arguments:
path Path to a folder containing a recipe (conanfile.py or conanfile.txt) or to a recipe file. e.g., ./my_project/conanfile.txt.
path Path to a folder containing a recipe (conanfile.py or
conanfile.txt) or to a recipe file. e.g.,
./my_project/conanfile.txt.

optional arguments:
-h, --help show this help message and exit
-v [V] Level of detail of the output. Valid options from less verbose to more verbose: -vquiet, -verror, -vwarning, -vnotice, -vstatus, -v or -vverbose, -vv or -vdebug, -vvv or -vtrace
--logger Show the output with log format, with time, type and message.
-v [V] Level of detail of the output. Valid options from less
verbose to more verbose: -vquiet, -verror, -vwarning,
-vnotice, -vstatus, -v or -vverbose, -vv or -vdebug,
-vvv or -vtrace
--logger Show the output with log format, with time, type and
message.
--name NAME Provide a package name if not specified in conanfile
--version VERSION Provide a package version if not specified in conanfile
--version VERSION Provide a package version if not specified in
conanfile
--user USER Provide a user if not specified in conanfile
--channel CHANNEL Provide a channel if not specified in conanfil
--channel CHANNEL Provide a channel if not specified in conanfile
-of OUTPUT_FOLDER, --output-folder OUTPUT_FOLDER
The root output folder for generated and build files
-b BUILD, --build BUILD
Optional, specify which packages to build from source. Combining multiple '--build' options on one command line is allowed. For dependencies, the optional 'build_policy' attribute in their conanfile.py takes
precedence over the command line parameter. Possible parameters: --build="*" Force build for all packages, do not use binary packages. --build=never Disallow build for all packages, use binary packages or fail if
a binary package is not found. Cannot be combined with other '--build' options. --build=missing Build packages from source whose binary package is not found. --build=cascade Build packages from source that have
at least one dependency being built from source. --build=[pattern] Build packages from source whose package reference matches the pattern. The pattern uses 'fnmatch' style wildcards. --build=![pattern] Excluded
packages, which will not be built from the source, whose package reference matches the pattern. The pattern uses 'fnmatch' style wildcards. Default behavior: If you omit the '--build' option, the 'build_policy'
attribute in conanfile.py will be used if it exists, otherwise the behavior is like '--build=never'.
Optional, specify which packages to build from source.
Combining multiple '--build' options on one command
line is allowed. Possible values: --build="*" Force
build from source for all packages. --build=never
Disallow build for all packages, use binary packages
or fail if a binary package is not found. Cannot be
combined with other '--build' options. --build=missing
Build packages from source whose binary package is not
found. --build=cascade Build packages from source that
have at least one dependency being built from source.
--build=[pattern] Build packages from source whose
package reference matches the pattern. The pattern
uses 'fnmatch' style wildcards. --build=![pattern]
Excluded packages, which will not be built from the
source, whose package reference matches the pattern.
The pattern uses 'fnmatch' style wildcards.
--build=missing:[pattern] Build from source if a
compatible binary does not exist, only for packages
matching pattern.
-r REMOTE, --remote REMOTE
Look in the specified remote or remotes server
-nr, --no-remote Do not use remote, resolve exclusively in the cache
-u, --update Will check the remote and in case a newer version and/or revision of the dependencies exists there, it will install those in the local cache. When using version ranges, it will install the latest version that
satisfies the range. Also, if using revisions, it will update to the latest revision for the resolved version range.
-u, --update Will check the remote and in case a newer version
and/or revision of the dependencies exists there, it
will install those in the local cache. When using
version ranges, it will install the latest version
that satisfies the range. Also, if using revisions, it
will update to the latest revision for the resolved
version range.
-o OPTIONS_HOST, --options OPTIONS_HOST
Define options values (host machine), e.g.: -o Pkg:with_qt=true
Define options values (host machine), e.g.: -o
Pkg:with_qt=true
-o:b OPTIONS_BUILD, --options:build OPTIONS_BUILD
Define options values (build machine), e.g.: -o:b Pkg:with_qt=true
Define options values (build machine), e.g.: -o:b
Pkg:with_qt=true
-o:h OPTIONS_HOST, --options:host OPTIONS_HOST
Define options values (host machine), e.g.: -o:h Pkg:with_qt=true
Define options values (host machine), e.g.: -o:h
Pkg:with_qt=true
-pr PROFILE_HOST, --profile PROFILE_HOST
Apply the specified profile to the host machine
-pr:b PROFILE_BUILD, --profile:build PROFILE_BUILD
Apply the specified profile to the build machine
-pr:h PROFILE_HOST, --profile:host PROFILE_HOST
Apply the specified profile to the host machine
-s SETTINGS_HOST, --settings SETTINGS_HOST
Settings to build the package, overwriting the defaults (host machine). e.g.: -s compiler=gcc
Settings to build the package, overwriting the
defaults (host machine). e.g.: -s compiler=gcc
-s:b SETTINGS_BUILD, --settings:build SETTINGS_BUILD
Settings to build the package, overwriting the defaults (build machine). e.g.: -s:b compiler=gcc
Settings to build the package, overwriting the
defaults (build machine). e.g.: -s:b compiler=gcc
-s:h SETTINGS_HOST, --settings:host SETTINGS_HOST
Settings to build the package, overwriting the defaults (host machine). e.g.: -s:h compiler=gcc
Settings to build the package, overwriting the
defaults (host machine). e.g.: -s:h compiler=gcc
-c CONF_HOST, --conf CONF_HOST
Configuration to build the package, overwriting the defaults (host machine). e.g.: -c tools.cmake.cmaketoolchain:generator=Xcode
Configuration to build the package, overwriting the
defaults (host machine). e.g.: -c
tools.cmake.cmaketoolchain:generator=Xcode
-c:b CONF_BUILD, --conf:build CONF_BUILD
Configuration to build the package, overwriting the defaults (build machine). e.g.: -c:b tools.cmake.cmaketoolchain:generator=Xcode
Configuration to build the package, overwriting the
defaults (build machine). e.g.: -c:b
tools.cmake.cmaketoolchain:generator=Xcode
-c:h CONF_HOST, --conf:host CONF_HOST
Configuration to build the package, overwriting the defaults (host machine). e.g.: -c:h tools.cmake.cmaketoolchain:generator=Xcode
Configuration to build the package, overwriting the
defaults (host machine). e.g.: -c:h
tools.cmake.cmaketoolchain:generator=Xcode
-l LOCKFILE, --lockfile LOCKFILE
Path to a lockfile.
--lockfile-partial Do not raise an error if some dependency is not found in lockfile
Path to a lockfile. Use --lockfile="" to avoid
automatic use of existing 'conan.lock' file
--lockfile-partial Do not raise an error if some dependency is not found
in lockfile
--lockfile-out LOCKFILE_OUT
Filename of the updated lockfile
--lockfile-packages Lock package-id and package-revision information
--lockfile-clean remove unused
--lockfile-clean Remove unused entries from the lockfile


The ``conan build`` command installs the recipe specified in ``path`` and calls its ``build`` method.
73 changes: 55 additions & 18 deletions reference/commands/cache.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,38 +3,43 @@
conan cache
===========

Perform file operations in the local cache (of recipes and/or packages).


conan cache path
----------------

.. code-block:: bash
.. code-block:: text

$ conan cache path -h
usage: conan cache path [-h] [-v [V]] [--logger]
[--folder {export_source,source,build}]
reference

Shows the path in the Conan cache af a given reference
Show the path to the Conan cache for a given reference.

positional arguments:
reference Recipe reference or Package reference
reference Recipe reference or Package reference

optional arguments:
-h, --help show this help message and exit
-v [V] Level of detail of the output. Valid options from less verbose to more
verbose: -vquiet, -verror, -vwarning, -vnotice, -vstatus, -v or
-vverbose, -vv or -vdebug, -vvv or -vtrace
--logger Show the output with log format, with time, type and message.
--folder {exports,exports_sources,sources,build,package}
Show the path to the specified element. The 'build' and 'package'
requires a package reference. If not specified it shows 'exports' path
-h, --help show this help message and exit
-v [V] Level of detail of the output. Valid options from less
verbose to more verbose: -vquiet, -verror, -vwarning,
-vnotice, -vstatus, -v or -vverbose, -vv or -vdebug,
-vvv or -vtrace
--logger Show the output with log format, with time, type and
message.
--folder {export_source,source,build}
Path to show. The 'build' requires a package
reference. If not specified it shows 'exports' path


The ``conan cache path`` returns the path in the cache of a given reference. Depending on the reference, it
could return the path of a recipe, or the path to a package binary.

Let's say that we have created a package in our current cache with:

.. code-block:: bash
.. code-block:: text

$ conan new cmake_lib -d name=pkg -d version=0.1
$ conan create .
Expand All @@ -48,7 +53,7 @@ Let's say that we have created a package in our current cache with:

And now we are interested in obtaining the path where our ``pkg/0.1`` recipe ``conanfile.py`` has been exported:

.. code-block:: bash
.. code-block:: text

$ conan cache path pkg/0.1
<path to conan cache>/p/5cb229164ec1d245/e
Expand All @@ -60,7 +65,7 @@ By default, if the recipe revision is not specified, it means the "latest" revis
also be made explicit by the literal ``#latest``, and also any recipe revision can be explicitly defined,
these commands are equivalent to the above:

.. code-block:: bash
.. code-block:: text

$ conan cache path pkg/0.1#latest
<path to conan cache>/p/5cb229164ec1d245/e
Expand All @@ -75,7 +80,7 @@ Together with the recipe folder, there are a two other folders that are common t
produced with this recipe: the "export_source" folder and the "source" folder. Both can be
obtained with:

.. code-block:: bash
.. code-block:: text

$ conan cache path pkg/0.1 --folder=export_source
<path to conan cache>/p/5cb229164ec1d245/es
Expand All @@ -102,7 +107,7 @@ binary is retrieve from a server.

It is also possible to obtain the folders of the binary packages providing the ``package_id``:

.. code-block:: bash
.. code-block:: text

# Your package_id might be different, it depends on the platform
# Check the "conan create" output to obtain yours
Expand All @@ -116,7 +121,7 @@ As above, by default it will resolve to the "latest" recipe revision and package
The command above is equal to explicitly defining ``#latest`` or the exact revisions.
All the commands below are equivalent to the above one:

.. code-block:: bash
.. code-block:: text

$ conan cache path pkg/0.1#latest:2401fa1d188d289bb25c37cfa3317e13e377a351
<path to conan cache>/p/1cae77d6250c23b7/p
Expand All @@ -130,7 +135,7 @@ All the commands below are equivalent to the above one:

It is possible to access the "build" folder with all the temporary build artifacts:

.. code-block:: bash
.. code-block:: text

$ conan cache path pkg/0.1:2401fa1d188d289bb25c37cfa3317e13e377a351 --folder=build
<path to conan cache>/p/1cae77d6250c23b7/b
Expand All @@ -149,3 +154,35 @@ Again, the "build" folder will only exist if the package was built from source.
package storage must be considered **read-only**. Do not modify, change, remove or add files from the cache.
- If you are using this command to obtain the path to artifacts and then copying them, consider the usage of a ``deployer``
instead. In the general case, extracting artifacts from the cache manually is discouraged.


conan cache clean
-----------------

.. code-block:: text

$ conan cache clean -h
usage: conan cache clean [-h] [-v [V]] [--logger] [-s] [-b] [-d]
[-p PACKAGE_QUERY]
pattern

Remove non-critical folders from the cache, like source, build and/or download
(.tgz store) ones.

positional arguments:
pattern Selection pattern for references to clean

optional arguments:
-h, --help show this help message and exit
-v [V] Level of detail of the output. Valid options from less
verbose to more verbose: -vquiet, -verror, -vwarning,
-vnotice, -vstatus, -v or -vverbose, -vv or -vdebug,
-vvv or -vtrace
--logger Show the output with log format, with time, type and
message.
-s, --source Clean source folders
-b, --build Clean build folders
-d, --download Clean download folders
-p PACKAGE_QUERY, --package-query PACKAGE_QUERY
Remove only the packages matching a specific query,
e.g., os=Windows AND (arch=x86 OR compiler=gcc)
Loading