Automatic deploy (build number 20)

2.1/_sources/examples/tools/autotools/autotools.rst.txt

@@ -9,4 +9,5 @@ tools.autotools
    :maxdepth: 2
 
 
-   autotools_toolchain/build_project_autotools_toolchain
+   build_project_autotools_toolchain
+   create_your_first_package

2.1/_sources/examples/tools/autotools/build_project_autotools_toolchain.rst.txt

@@ -0,0 +1,185 @@
+.. _examples_tools_autotools_autotools_toolchain_build_project_autotools_toolchain:
+
+Build a simple Autotools project with Conan dependencies
+========================================================
+
+.. warning::
+
+  This example will only work for Linux and OSX environments and does not support Windows directly, including msys2/cygwin subsystems.
+  However, Windows Subsystem for Linux (WSL) should work since it provides a Linux environment. While Conan offers `win_bash = True` 
+  for some level of support in Windows environments with Autotools, it's not applicable in this tutorial.
+
+
+In this example, we are going to create a string formatter application
+that uses one of the most popular C++ libraries: `fmt <https://fmt.dev/latest/index.html/>`_.
+
+We'll use `Autotools <https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html>`_ as build system and `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`_ as a helper tool in this case, so you should get them installed
+on Linux and Mac before going forward with this example.
+
+Please, first clone the sources to recreate this project. You can find them in the
+`examples2 repository <https://github.com/conan-io/examples2>`_ on GitHub:
+
+.. code-block:: shell
+
+    git clone https://github.com/conan-io/examples2.git
+    cd examples2/examples/tools/autotools/autotoolstoolchain/string_formatter
+
+We start with a very simple C++ language project with the following structure:
+
+.. code-block:: text
+
+    .
+    ├── configure.ac
+    ├── Makefile.am
+    ├── conanfile.txt
+    └── src
+        └── main.cpp
+
+This project contains a basic `configure.ac <https://www.gnu.org/software/autoconf/manual/autoconf-2.60/html_node/Writing-configure_002eac.html>_` including the **fmt** pkg-config dependency and the
+source code for the string formatter program in *main.cpp*.
+
+Let's have a look at the *main.cpp* file, it only prints a simple message but uses ``fmt::print`` method for it.
+
+.. code-block:: cpp
+    :caption: **main.cpp**
+
+    #include <cstdlib>
+    #include <fmt/core.h>
+
+    int main() {
+        fmt::print("{} - The C++ Package Manager!\n", "Conan");
+        return EXIT_SUCCESS;
+    }
+
+The ``configure.ac`` file checks for a C++ compiler using the ``AC_PROG_CXX`` macro and also checks for the ``fmt.pc`` pkg-config module using the ``PKG_CHECK_MODULES`` macro.
+
+.. code-block:: text
+    :caption: **configure.ac**
+
+    AC_INIT([stringformatter], [0.1.0])
+    AM_INIT_AUTOMAKE([1.10 -Wall no-define foreign])
+    AC_CONFIG_SRCDIR([src/main.cpp])
+    AC_CONFIG_FILES([Makefile])
+    PKG_CHECK_MODULES([fmt], [fmt])
+    AC_PROG_CXX
+    AC_OUTPUT
+
+The *Makefile.am* specifies that ``string_formatter`` is the expected executable and that it should be linked to the ``fmt`` library.
+
+.. code-block:: text
+    :caption: **Makefile.am**
+
+    AUTOMAKE_OPTIONS = subdir-objects
+    ACLOCAL_AMFLAGS = ${ACLOCAL_FLAGS}
+
+    bin_PROGRAMS = string_formatter
+    string_formatter_SOURCES = src/main.cpp
+    string_formatter_CPPFLAGS = $(fmt_CFLAGS)
+    string_formatter_LDADD = $(fmt_LIBS)
+
+The *conanfile.txt* looks simple as it just installs the **fmt** package and uses two generators to build our project.
+
+.. code-block:: ini
+    :caption: **conanfile.txt**
+
+    [requires]
+    fmt/9.1.0
+
+    [generators]
+    AutotoolsToolchain
+    PkgConfigDeps
+
+In this case, we will use :ref:`PkgConfigDeps<conan_tools_gnu_pkgconfigdeps>` to generate information about where the **fmt** library
+files are installed thanks to the `*.pc` files and :ref:`AutotoolsToolchain<conan_tools_gnu_autotoolstoolchain>` to pass build information
+to *autotools* using a `conanbuild[.sh|.bat]` file that describes the compilation environment.
+
+We will use Conan to install **fmt** library, generate a toolchain for Autotools, and, .pc files for find **fmt** by pkg-config.
+
+
+Building on Linux and macOS
+---------------------------
+
+First, we should install some requirements. On Linux you need to have ``automake`` , ``pkgconf`` and ``make`` packages installed,
+their packages names should vary according to the Linux distribution, but essentially,
+it should include all tools (aclocal, automake, autoconf and make) that you will need to build the following example.
+
+For this example, we will not consider a specific Conan profile, but ``fmt`` is highly compatible with many different configurations.
+So it should work mostly with versions of GCC and Clang compiler.
+
+As the first step, we should install all dependencies listed in the ``conanfile.txt``.
+The command :ref: `conan install<reference_commands_install>` will not only install the ``fmt`` package,
+but also build it from sources in case your profile does not match with a pre-built binary in your remotes.
+Plus, it will provide these generators listed in the ``conanfile.txt``
+
+.. code-block:: shell
+
+    conan install . --build=missing
+
+After running ``conan install`` command, we should have new files present in the *string_formatter* folder:
+
+.. code-block:: text
+
+
+    └── string_formatter
+        ├── Makefile.am
+        ├── conanautotoolstoolchain.sh
+        ├── conanbuild.conf
+        ├── conanbuild.sh
+        ├── conanbuildenv-release-armv8.sh
+        ├── conanfile.txt
+        ├── conanrun.sh
+        ├── conanrunenv-release-armv8.sh
+        ├── configure.ac
+        ├── deactivate_conanbuild.sh
+        ├── deactivate_conanrun.sh
+        ├── fmt-_fmt.pc
+        ├── fmt.pc
+        ├── run_example.sh
+        └── src
+            └── main.cpp
+
+
+These files are the result of those generators listed in the ``conanfile.txt``.
+Once all files needed to build the example are generated and ``fmt`` is installed, now we can load the script ``conanbuild.sh``.
+
+.. code-block:: shell
+
+    source conanbuild.sh
+
+The ``conanbuild.sh`` is a default file generated by the :ref:`VirtualBuildEnv<conan_tools_env_virtualbuildenv>` and helps us to load other
+script files, so we don't need to execute more manual steps to load each generator file. It will load ``conanautotoolstoolchain.sh``,
+generated by `AutotoolsToolchain`, which defines environment variables according to our
+Conan profile, used when running ``conan install`` command. Those environment variables configured are related to the compiler
+and ``autotools``, like ``CFLAGS``, ``CPPFLAGS``, ``LDFLAGS``, and ``PKG_CONFIG_PATH``.
+
+As the next step, we can configure the project by running the following commands in sequence:
+
+.. code-block:: shell
+
+    aclocal
+    automake --add-missing
+    autoconf
+    ./configure
+
+The `aclocal <https://www.gnu.org/software/automake/manual/html_node/aclocal-Invocation.html>`_ command will read the file ``configure.ac``
+and generate a new file named ``aclocal.m4``, which contains macros needed by the ``automake``. As the second step,
+the `automake <https://www.gnu.org/software/automake/manual/automake.html>`_ command will read the ``Makefile.am``, and will generate the file ``Makefile.in``.
+So the command `autoconf <https://www.gnu.org/software/autoconf/>`_ will use those files and generate the ``configure`` file.
+Once we run ``configure``, all environment variables will be consumed. The ``fmt.pc`` will be loaded at this step too,
+as ``autotools`` uses the custom ``PKG_CONFIG_PATH`` to find it.
+
+Then, finally, we can build the project to generate the string formatter application.
+Now we run the ``make`` command, which will consume the ``Makefile`` generated by ``autotools``.
+
+.. code-block:: shell
+
+    make
+
+The ``make`` command will read the ``Makefile`` and invoke the compiler, then, build the ``main.cpp``, generating the executable ``string_formatter`` in the same folder.
+
+.. code-block:: shell
+
+    ./string_formatter
+    Conan - The C++ Package Manager!
+
+The final output is the result of a new application, printing a message with the help of ``fmt`` library, and built by ``Autotools``.

2.1/_sources/examples/tools/autotools/create_your_first_package.rst.txt

@@ -0,0 +1,148 @@
+.. _examples_tools_autotools_create_first_package:
+
+Create your first Conan package with Autotools
+==============================================
+
+.. warning::
+
+  This example will only work for Linux and OSX environments and does not support Windows directly, including msys2/cygwin subsystems.
+  However, Windows Subsystem for Linux (WSL) should work since it provides a Linux environment. While Conan offers `win_bash = True` 
+  for some level of support in Windows environments with Autotools, it's not applicable in this tutorial.
+
+
+In the :ref:`Create your first Conan package tutorial<creating_packages_create_your_first_conan_package>`
+CMake was used as the build system. If you haven't read that section, read it first to familiarize
+yourself with the ``conanfile.py`` and ``test_package`` concepts, then come back to read
+about the specifics of the ``Autotools`` package creation.
+
+Use the :command:`conan new` command to create a "Hello World" C++ library example project:
+
+.. code-block:: bash
+
+    $ conan new autotools_lib -d name=hello -d version=0.1
+
+
+This will create a Conan package project with the following structure.
+
+.. code-block:: text
+
+  ├── conanfile.py
+  ├── configure.ac
+  ├── Makefile.am
+  ├── src
+  │   ├── hello.h
+  │   ├── hello.cpp
+  │   └── Makefile.am
+  └── test_package
+      ├── conanfile.py
+      ├── configure.ac
+      ├── mainc.pp
+      └── Makefile.am
+
+
+The structure and files are very similar to the previous CMake example:
+
+- **conanfile.py**: On the root folder, there is a *conanfile.py* which is the main recipe
+  file, responsible for defining how the package is built and consumed.
+- **configure.ac**: An autotools configuration script, that contains the necessary macros
+  and references the ``Makefiles`` it needs to configure.
+- **Makefile.am**: A Makefile configuration file, defining only ``SUBDIRS = src``
+- **src** folder: the folder that contains the simple C++ "hello" library.
+- **src/Makefile.am**: Makefile configuration file containing the library definition and source files
+  like ``libhello_la_SOURCES = hello.cpp hello.h``
+- **test_package** folder: contains an *example* application that will require
+  and link with the created package. In this case the ``test_package`` also contains an autotools
+  project, but it is possible to have the ``test_package`` using
+  other build system as CMake if desired. It is not mandatory that the test_package is using
+  the same build system as the package.
+
+Let's have a look at the package recipe *conanfile.py* (only the relevant new parts):
+
+.. code-block:: python
+
+    exports_sources = "configure.ac", "Makefile.am", "src/*"
+
+    def layout(self):
+        basic_layout(self)
+
+    def generate(self):
+        at_toolchain = AutotoolsToolchain(self)
+        at_toolchain.generate()
+
+    def build(self):
+        autotools = Autotools(self)
+        autotools.autoreconf()
+        autotools.configure()
+        autotools.make()
+
+    def package(self):
+        autotools = Autotools(self)
+        autotools.install()
+        fix_apple_shared_install_name(self)
+
+Let's explain the different sections of the recipe briefly:
+
+- The ``layout()`` defines a ``basic_layout()``, this is less flexible than a CMake one, so it
+  doesn't allow any parametrization.
+- The ``generate()`` method calls ``AutotoolsToolchain`` that can generate a ``conanautotoolstoolchain``
+  environment script defining environment variables like ``CXXFLAGS`` or ``LDFLAGS`` that will be used
+  by the ``Makefiles`` to map the Conan input settings into compile flags. If the project had dependencies
+  with Conan ``requires``, it should add ``PkgConfigDeps`` too
+- The ``build()`` method uses the ``Autotools()`` helper to drive the build, calling the different configure
+  and build steps.
+- The ``package()`` method uses the ``Autotools`` install functionality to define and copy to the package 
+  folder the final artifacts. Note the template also includes a call to ``fix_apple_shared_install_name()``
+  that uses OSX *install_name_tool* utility to set ``@rpath``to fix the ``LC_ID_DYLIB`` and ``LC_LOAD_DYLIB``
+  fields on Apple dylibs, because it is very unusual that autotools project will manage to do this (CMake can do it) .
+
+
+Let's build the package from sources with the current default configuration, and then let
+the ``test_package`` folder test the package:
+
+.. code-block:: bash
+
+    $ conan create .
+
+    ...
+    ======== Testing the package: Executing test ========
+    hello/0.1 (test package): Running test()
+    hello/0.1 (test package): RUN: ./main
+    hello/0.1: Hello World Release!
+      hello/0.1: __x86_64__ defined
+      hello/0.1: _GLIBCXX_USE_CXX11_ABI 1
+      hello/0.1: __cplusplus201703
+      hello/0.1: __GNUC__11
+      hello/0.1: __GNUC_MINOR__1
+    hello/0.1 test_package
+
+
+We can now validate that the recipe and the package binary are in the cache:
+
+
+.. code-block:: bash
+
+    $ conan list hello/1.0:*
+    Local Cache:
+      hello
+        hello/1.0
+          revisions
+            5b151b3f08144bf25131266eb306ddff (2024-03-06 12:03:52 UTC)
+              packages
+                8631cf963dbbb4d7a378a64a6fd1dc57558bc2fe
+                  info
+                    settings
+                      arch: x86_64
+                      build_type: Release
+                      compiler: gcc
+                      compiler.cppstd: gnu17
+                      compiler.libcxx: libstdc++11
+                      compiler.version: 11
+                      os: Linux
+                    options
+                      fPIC: True
+                      shared: False
+
+
+.. seealso::
+
+    - :ref:`GNU built-in integrations reference<conan_tools_gnu>`.

2.1/_sources/tutorial/creating_packages/create_your_first_package.rst.txt

@@ -339,5 +339,6 @@ An **important** note: the Conan cache is private to the Conan client - modifyin
 
   - :ref:`Create your first Conan package with Visual Studio/MSBuild<examples_tools_microsoft_create_first_package>`.
   - :ref:`Create your first Conan package with Meson<examples_tools_meson_create_first_package>`.
+  - :ref:`Create your first Conan package with Autotools (only Linux)<examples_tools_autotools_create_first_package>`.
   - :ref:`CMake built-in integrations reference<conan_tools_cmake>`.
   - :ref:`conan create command reference<reference_commands_create>` and :ref:`Conan list command reference<reference_commands_list>`.

2.1/examples/tools.html

@@ -149,7 +149,8 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="tools/autotools/autotools.html">tools.autotools</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="tools/autotools/autotools_toolchain/build_project_autotools_toolchain.html">Build a simple Autotools project using Conan</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tools/autotools/build_project_autotools_toolchain.html">Build a simple Autotools project with Conan dependencies</a></li>
+<li class="toctree-l2"><a class="reference internal" href="tools/autotools/create_your_first_package.html">Create your first Conan package with Autotools</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="tools/scm/git/capture_scm/git_capture_scm.html">Capturing Git scm information</a><ul>