Tutorial for local flow (#2968)

* wip * wip * wip * wip * wip * fix spelling * Update tutorial/developing_packages/local_package_development_flow.rst Co-authored-by: James <james@conan.io> * fix format * remove test * add note --------- Co-authored-by: James <james@conan.io>
conan-io · Feb 16, 2023 · 4d8b82e · 4d8b82e
1 parent 807f3b3
commit 4d8b82e
Show file tree

Hide file tree

Showing 14 changed files with 472 additions and 29 deletions.
diff --git a/examples/conanfile/layout/third_party_libraries.rst b/examples/conanfile/layout/third_party_libraries.rst
@@ -45,7 +45,7 @@ The ``conanfile.py`` would look like this:
             # the downloaded soures will be inside the "src" subfolder
             get(self, "https://github.com/conan-io/libhello/archive/refs/heads/main.zip", 
                 strip_root=True)
-            # Please, be aware that using the head of the branch instead of an inmutable tag
+            # Please, be aware that using the head of the branch instead of an immutable tag
             # or commit is not a good practice in general as the branch may change the contents
 
             # patching, replacing, happens here

diff --git a/reference/commands.rst b/reference/commands.rst
@@ -43,31 +43,29 @@ and these :ref:`custom command examples <examples_extensions_custom_commands>`
 
 **Creator commands:**
 
-.. toctree::
-   :caption: Creator commands
-   :maxdepth: 1
-   :hidden:
-
-   commands/create
-   commands/export
-   commands/new
-   commands/test
-   commands/upload
+..  toctree::
+    :caption: Creator commands
+    :maxdepth: 1
+    :hidden:
+
+    commands/build
+    commands/create
+    commands/download
+    commands/editable
+    commands/export
+    commands/export-pkg
+    commands/new
+    commands/source
+    commands/test
+    commands/upload
 
+- :doc:`conan build <commands/build>`: Install package and call its build method
 - :doc:`conan create <commands/create>`: Create a package from a recipe
+- :doc:`conan download <commands/download>`: Download (without install) a single conan package from a remote server.
+- :doc:`conan editable <commands/editable>`: Allows working with a package in user folder
 - :doc:`conan export <commands/export>`: Export a recipe to the Conan package cache
+- :doc:`conan export-pkg <commands/export-pkg>`: Create a package directly from pre-compiled binaries
 - :doc:`conan new <commands/new>`: Create a new recipe from a predefined template
+- :doc:`conan source <commands/source>`: Calls the source() method
 - :doc:`conan test <commands/test>`: Test a package
 - :doc:`conan upload <commands/upload>`: Upload packages from the local cache to a specified remote
-
-
-**Development commands**
-
-.. toctree::
-   :caption: Development commands
-   :maxdepth: 1
-   :hidden:
-
-   commands/build
-
-- :doc:`conan build <commands/build>`: Install package and call its build method
diff --git a/reference/commands/build.rst b/reference/commands/build.rst
@@ -1,3 +1,5 @@
+.. _reference_commands_build:
+
 conan build
 ===========
 

diff --git a/reference/commands/download.rst b/reference/commands/download.rst
@@ -0,0 +1,31 @@
+.. _reference_commands_download:
+
+conan download
+==============
+
+.. code-block:: bash
+
+    $ conan download --help
+    usage: conan download [-h] [-v [V]] [--logger] [--only-recipe] [-p PACKAGE_QUERY] -r REMOTE reference
+
+    Download (without install) a single conan package from a remote server.
+
+    It downloads just the package, but not its transitive dependencies, and it will not call
+    any generate, generators or deployers.
+    It can download multiple packages if patterns are used, and also queries over the package
+    binaries can be provided.
+
+    positional arguments:
+    reference             Recipe reference or package reference, can contain * as wildcard at any reference field. If
+                            revision is not specified, it is assumed latest one.
+
+    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.
+    --only-recipe         Download only the recipe/s, not the binary packages.
+    -p PACKAGE_QUERY, --package-query PACKAGE_QUERY
+                            Only upload packages matching a specific query. e.g: os=Windows AND (arch=x86 OR compiler=gcc)
+    -r REMOTE, --remote REMOTE
+                            Download from this specific remote
diff --git a/reference/commands/editable.rst b/reference/commands/editable.rst
@@ -0,0 +1,24 @@
+.. _reference_commands_editable:
+
+conan editable
+==============
+
+.. code-block:: bash
+
+    $ conan editable --help
+    usage: conan editable [-h] [-v [V]] [--logger] {add,list,remove} ...
+
+    Allows working with a package in user folder
+
+    positional arguments:
+    {add,list,remove}  sub-command help
+        add              Define the given <path> location as the package <reference>, so when this package is required, it is
+                        used from this <path> location instead of from the cache
+        list             List packages in editable mode
+        remove           Remove the "editable" mode for this 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.
diff --git a/reference/commands/export-pkg.rst b/reference/commands/export-pkg.rst
@@ -0,0 +1,67 @@
+.. _reference_commands_export-pkg:
+
+conan export-pkg
+================
+
+.. code-block:: bash
+
+    $ conan export-pkg --help
+    usage: conan export-pkg [-h] [-f FORMAT] [-v [V]] [--logger] [-of OUTPUT_FOLDER] [--name NAME] [--version VERSION]
+                            [--user USER] [--channel CHANNEL] [-l LOCKFILE] [--lockfile-partial] [--lockfile-out LOCKFILE_OUT]
+                            [--lockfile-packages] [--lockfile-clean] [-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]
+                            path
+
+    Create a package directly from pre-compiled binaries
+
+    positional arguments:
+    path                  Path to a folder containing a recipe (conanfile.py)
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    -f FORMAT, --format FORMAT
+                            Select the output format: json
+    -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.
+    -of OUTPUT_FOLDER, --output-folder OUTPUT_FOLDER
+                            The root output folder for generated and build files
+    --name NAME           Provide a package name 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
+    -l LOCKFILE, --lockfile 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
+    -o OPTIONS_HOST, --options OPTIONS_HOST
+                            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
+    -o:h OPTIONS_HOST, --options:host OPTIONS_HOST
+                            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
+    -s:b SETTINGS_BUILD, --settings:build SETTINGS_BUILD
+                            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
+    -c CONF_HOST, --conf CONF_HOST
+                            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
+    -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
diff --git a/reference/commands/source.rst b/reference/commands/source.rst
@@ -0,0 +1,25 @@
+.. _reference_commands_source:
+
+conan source
+============
+
+.. code-block:: bash
+
+    $ conan source --help
+    usage: conan source [-h] [-v [V]] [--logger] [--name NAME] [--version VERSION] [--user USER] [--channel CHANNEL] [path]
+
+    Calls the source() 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.
+
+    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.
+    --name NAME        Provide a package name 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 conanfile
diff --git a/reference/commands/test.rst b/reference/commands/test.rst
@@ -1,3 +1,5 @@
+.. _reference_commands_test:
+
 conan test
 ===========
 

diff --git a/tutorial/creating_packages/add_dependencies_to_packages.rst b/tutorial/creating_packages/add_dependencies_to_packages.rst
@@ -47,7 +47,7 @@ Let's check the relevant parts:
         def source(self):
             git = Git(self)
             git.clone(url="https://github.com/conan-io/libhello.git", target=".")
-            # Please, be aware that using the head of the branch instead of an inmutable tag
+            # Please, be aware that using the head of the branch instead of an immutable tag
             # or commit is not a good practice in general
             git.checkout("require_fmt")
 

diff --git a/tutorial/creating_packages/build_packages.rst b/tutorial/creating_packages/build_packages.rst
@@ -42,7 +42,7 @@ Changes introduced in the recipe
         def source(self):
             git = Git(self)
             git.clone(url="https://github.com/conan-io/libhello.git", target=".")
-            # Please, be aware that using the head of the branch instead of an inmutable tag
+            # Please, be aware that using the head of the branch instead of an immutable tag
             # or commit is not a good practice in general
             git.checkout("with_tests")
 

diff --git a/tutorial/creating_packages/define_package_information.rst b/tutorial/creating_packages/define_package_information.rst
@@ -159,7 +159,7 @@ conditionally set the library name depending on the ``self.options.shared`` opti
         def source(self):
             git = Git(self)
             git.clone(url="https://github.com/conan-io/libhello.git", target=".")
-            # Please, be aware that using the head of the branch instead of an inmutable tag
+            # Please, be aware that using the head of the branch instead of an immutable tag
             # or commit is not a good practice in general
             git.checkout("package_info")
 

diff --git a/tutorial/creating_packages/other_types_of_packages/package_prebuilt_binaries.rst b/tutorial/creating_packages/other_types_of_packages/package_prebuilt_binaries.rst
@@ -1,3 +1,5 @@
+.. _creating_packages_other_prebuilt:
+
 Package prebuilt binaries
 =========================
 

diff --git a/tutorial/creating_packages/preparing_the_build.rst b/tutorial/creating_packages/preparing_the_build.rst
@@ -64,7 +64,7 @@ Let's check the relevant parts:
         def source(self):
             git = Git(self)
             git.clone(url="https://github.com/conan-io/libhello.git", target=".")
-            # Please, be aware that using the head of the branch instead of an inmutable tag
+            # Please, be aware that using the head of the branch instead of an immutable tag
             # or commit is not a good practice in general
             git.checkout("optional_fmt")