diff --git a/_themes/conan/static/css/book.jpg b/_themes/conan/static/css/book.jpg new file mode 100644 index 000000000000..8b04466580a4 Binary files /dev/null and b/_themes/conan/static/css/book.jpg differ diff --git a/_themes/conan/static/css/signup.css b/_themes/conan/static/css/signup.css index 70fe9bbafb96..8f5c4bc98d36 100644 --- a/_themes/conan/static/css/signup.css +++ b/_themes/conan/static/css/signup.css @@ -84,4 +84,19 @@ font-size: 17px !important; color: #C3C4C5 !important; width: 200px !important; +} + + +.out-reference-box{ + border: 1px solid #848484; + border-left: none; + border-right: none; + padding: 20px; + margin-bottom: 20px; + background-image: url("book.jpg"); + background-repeat: no-repeat; + background-position: left; + padding-left: 80px; + + } \ No newline at end of file diff --git a/conf.py b/conf.py index 0c26e9b39ada..15709f1de444 100644 --- a/conf.py +++ b/conf.py @@ -141,7 +141,7 @@ # 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'] +#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 diff --git a/faq/troubleshooting.rst b/faq/troubleshooting.rst index 9691dfa195a1..e673dd0acbe9 100644 --- a/faq/troubleshooting.rst +++ b/faq/troubleshooting.rst @@ -8,7 +8,7 @@ When you are installing packages (with ``conan install`` or ``conan test_package that you get an error like the following one: -.. code-block:: bash +.. code-block:: text WARN: Can't find a 'libzmq/4.2.0@memsharded/testing' package for the specified options and settings: - Settings: arch=x86_64, build_type=Release, compiler=gcc, compiler.libcxx=libstdc++, compiler.version=4.9, os=Windows diff --git a/howtos/cross_building.rst b/howtos/cross_building.rst index 59c9fba639e3..bbae1916c31a 100644 --- a/howtos/cross_building.rst +++ b/howtos/cross_building.rst @@ -47,10 +47,7 @@ We can try to build the hello world example for our own architecture with the `` ... > Hello World! - *** Running example, will fail by default, implement yours! *** - ERROR: Error 65280 while executing ./example -The test_package command fails because it's only a template and it's asking us to override the default example. So it's all ok, we've built a Hello World conan package for our own architecture. From Linux to Windows diff --git a/howtos/python_code_reuse.rst b/howtos/python_code_reuse.rst index 956414d27e24..a96da91fea95 100644 --- a/howtos/python_code_reuse.rst +++ b/howtos/python_code_reuse.rst @@ -111,19 +111,21 @@ The specified ``virtualenv`` generator will create an ``activate`` script (in Wi The above shows an interactive session, but you can import also the functionality in a regular python script. - Reusing python code in your recipes ------------------------------------- +----------------------------------- + +Requiring a python conan package +________________________________ As the conan recipes are python code itself, it is easy to reuse python packages in them. A basic recipe using the created package would be: .. code-block:: python from conans import ConanFile, tools - + class HelloPythonReuseConan(ConanFile): requires = "HelloPy/0.1@memsharded/testing" - + def build(self): with tools.pythonpath(self): from hello import hello @@ -143,3 +145,61 @@ In the above example, the code is reused in the ``build()`` method as an example ... $ conan build Hello World from Python! + + + +Sharing a python module +_______________________ + +Another approach is sharing a python module and exporting within the recipe. + +.. _split_conanfile: + +Lets write for example a ``msgs.py`` file and put it besides the ``conanfile.py``: + +.. code-block:: python + + def build_msg(output): + output.info("Building!") + +And then the main ``conanfile.py`` would be: + +.. code-block:: python + + from conans import ConanFile + from msgs import build_msg + + class ConanFileToolsTest(ConanFile): + name = "test" + version = "1.9" + exports = "msgs.py" # Important to remember! + + def build(self): + build_msg(self.output) + # ... + + +It is important to note that such ``msgs.py`` file **must be exported** too when exporting the package, +because package recipes must be self-contained. + +The code reuse can also be done in the form of a base class, something like a file ``base_conan.py`` + +.. code-block:: python + + from conans import ConanFile + + class ConanBase(ConanFile): + # common code here + +And then: + +.. code-block:: python + + from conans import ConanFile + from base_conan import ConanBase + + class ConanFileToolsTest(ConanBase): + name = "test" + version = "1.9" + + diff --git a/integrations.rst b/integrations.rst index 9c661e60a095..805df4426865 100644 --- a/integrations.rst +++ b/integrations.rst @@ -9,12 +9,11 @@ Integrations :maxdepth: 2 integrations/cmake - integrations/visual_studio integrations/makefile integrations/gcc + integrations/visual_studio integrations/xcode integrations/clion - integrations/virtualenv integrations/ninja integrations/qmake integrations/premake diff --git a/integrations/cmake.rst b/integrations/cmake.rst index d6aedbc54e52..bc2ad245f6fa 100644 --- a/integrations/cmake.rst +++ b/integrations/cmake.rst @@ -1,384 +1,18 @@ .. _cmake: |cmake_logo| CMake -__________________ +================== +Conan can be integrated with CMake using generators, build helpers and custom *findXXX.cmake* files: -If you are using *CMake* to build your project, you can use the *cmake* generator to manage all your requirements. +.. toctree:: + :maxdepth: 2 + cmake/cmake_generator + cmake/cmake_multi_generator + cmake/build_automation + cmake/find_packages -**conanfile.txt** -.. code-block:: text - - ... - - [generators] - cmake - - -When **conan install** is executed, a file named ``conanbuildinfo.cmake`` is created. - -We can include ``conanbuildinfo.cmake`` in our project's ``CMakeLists.txt`` to manage our requirements. - - -This is the ``CMakeLists.txt`` file we used in the :ref:`Getting started` example: - -.. code-block:: cmake - - project(FoundationTimer) - cmake_minimum_required(VERSION 2.8.12) - - include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) - conan_basic_setup() - - add_executable(timer timer.cpp) - target_link_libraries(timer ${CONAN_LIBS}) - - -- **include(conanbuildinfo.cmake)** will include the file generated by our **cmake** [generator] -- **conan_basic_setup()** call will asign to **CMake** all the needed variables for linking with our requirements. -- **${CONAN_LIBS}** contains the libraries to link with. So ``target_link_libraries()``, works just fine. - - -Let's take a look at the generated ``conanbuildinfo.cmake`` file: - - -.. code-block:: cmake - - set(CONAN_POCO_ROOT "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c") - set(CONAN_INCLUDE_DIRS_POCO "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c/include") - set(CONAN_LIB_DIRS_POCO "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c/lib") - set(CONAN_BIN_DIRS_POCO "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c/bin") - set(CONAN_LIBS_POCO PocoUtil PocoXML PocoJSON PocoMongoDB PocoNet PocoCrypto PocoData PocoDataSQLite PocoZip PocoFoundation pthread dl rt) - set(CONAN_DEFINES_POCO -Dshared=OFF -DPOCO_NO_AUTOMATIC_LIBS) - set(CONAN_COMPILE_DEFINITIONS_POCO shared=OFF POCO_NO_AUTOMATIC_LIBS) - set(CONAN_CXX_FLAGS_POCO "") - set(CONAN_SHARED_LINK_FLAGS_POCO "") - set(CONAN_EXE_LINKER_FLAGS_POCO "") - set(CONAN_C_FLAGS_POCO "") - - set(CONAN_ZLIB_ROOT "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e") - set(CONAN_INCLUDE_DIRS_ZLIB "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e/include") - set(CONAN_LIB_DIRS_ZLIB "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e/lib") - set(CONAN_BIN_DIRS_ZLIB "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e/bin") - set(CONAN_LIBS_ZLIB z) - set(CONAN_DEFINES_ZLIB ) - set(CONAN_COMPILE_DEFINITIONS_ZLIB ) - set(CONAN_CXX_FLAGS_ZLIB "") - set(CONAN_SHARED_LINK_FLAGS_ZLIB "") - set(CONAN_EXE_LINKER_FLAGS_ZLIB "") - set(CONAN_C_FLAGS_ZLIB "") - - set(CONAN_OPENSSL_ROOT "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535") - set(CONAN_INCLUDE_DIRS_OPENSSL "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535/include") - set(CONAN_LIB_DIRS_OPENSSL "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535/lib") - set(CONAN_BIN_DIRS_OPENSSL "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535/bin") - set(CONAN_LIBS_OPENSSL ssl crypto dl) - set(CONAN_DEFINES_OPENSSL ) - set(CONAN_COMPILE_DEFINITIONS_OPENSSL ) - set(CONAN_CXX_FLAGS_OPENSSL "") - set(CONAN_SHARED_LINK_FLAGS_OPENSSL "") - set(CONAN_EXE_LINKER_FLAGS_OPENSSL "") - set(CONAN_C_FLAGS_OPENSSL "") - - set(CONAN_PACKAGE_NAME Poco) - set(CONAN_PACKAGE_VERSION 1.7.3) - set(CONAN_DEPENDENCIES OpenSSL zlib) - set(CONAN_INCLUDE_DIRS "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c/include" - "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535/include" - "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e/include" ${CONAN_INCLUDE_DIRS}) - set(CONAN_LIB_DIRS "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c/lib" - "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535/lib" - "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e/lib" ${CONAN_LIB_DIRS}) - set(CONAN_BIN_DIRS "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c/bin" - "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535/bin" - "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e/bin" ${CONAN_BIN_DIRS}) - set(CONAN_LIBS PocoUtil PocoXML PocoJSON PocoMongoDB PocoNet PocoCrypto PocoData PocoDataSQLite PocoZip PocoFoundation pthread dl rt ssl crypto z ${CONAN_LIBS}) - set(CONAN_DEFINES -Dshared=OFF -DPOCO_NO_AUTOMATIC_LIBS ${CONAN_DEFINES}) - set(CONAN_CXX_FLAGS " ${CONAN_CXX_FLAGS}") - set(CONAN_SHARED_LINK_FLAGS " ${CONAN_SHARED_LINK_FLAGS}") - set(CONAN_EXE_LINKER_FLAGS " ${CONAN_EXE_LINKER_FLAGS}") - set(CONAN_C_FLAGS " ${CONAN_C_FLAGS}") - set(CONAN_CMAKE_MODULE_PATH "/home/laso/.conan/data/Poco/1.6.1/lasote/stable/package/afafc631e705f7296bec38318b28e4361ab6787c" "/home/laso/.conan/data/zlib/1.2.8/lasote/stable/package/3b92a20cb586af0d984797002d12b7120d38e95e" "/home/laso/.conan/data/OpenSSL/1.0.2d/lasote/stable/package/dd8a0e4171607d74dee9fd0c51153a922d849535" ${CONAN_CMAKE_MODULE_PATH}) - - macro(conan_basic_setup) - conan_check_compiler() - conan_output_dirs_setup() - conan_set_find_library_paths() - if(NOT "${ARGV0}" STREQUAL "TARGETS") - message(STATUS "Conan: Using cmake global configuration") - conan_global_flags() - else() - message(STATUS "Conan: Using cmake targets configuration") - conan_define_targets() - endif() - conan_set_rpath() - conan_set_vs_runtime() - conan_set_libcxx() - conan_set_find_paths() - endmacro() - - # ... macros code... - - -As we can see, conan is preparing some variables: - -* ``CONAN_INCLUDE_DIRS``: The headers folders from the requirements. -* ``CONAN_LIB_DIRS``: The library folders from the requirements. -* ``CONAN_BIN_DIRS``: The binary folders from the requirements. -* ``CONAN_LIBS``: The name of the libs we have to link with. -* ``CONAN_DEFINES``: Defines, observe that two are defined, "shared" and ``POCO_NO_AUTOMATIC_LIBS``, that correspond to options. -* ``CONAN_COMPILE_DEFINITIONS``: Defines, equal to ``CONAN_DEFINES`` but without the ``-D``, as required by cmake targets -* ``CONAN_C_FLAGS``: Flags for C. Not specified for Poco nor its requirements. -* ``CONAN_CXX_FLAGS``: Flags for CXX. Not specified for Poco nor its requirements. -* ``CONAN_SHARED_LINK_FLAGS``: Shared flags for CXX. Not specified for Poco nor its requirements. -* ``CONAN_EXE_LINKER_FLAGS``: Exe linker flags for CXX. Not specified for Poco nor its requirements. - - -Conan also provides the same variables isolated for each requirement, so you can handle the requirements individually: -``CONAN_POCO_ROOT, CONAN_INCLUDE_DIRS_POCO,CONAN_INCLUDE_DIRS_OPENSSL``, etc - -For the root package, the name, version and dependencies are also defined in ``CONAN_PACKAGE_NAME, CONAN_PACKAGE_VERSION, CONAN_DEPENDENCIES`` - - -Consuming ``conanbuildinfo.cmake`` -================================== - -The inclusion of ``conanbuildinfo.cmake`` doesn't alter cmake environment at all, it just provide ``CONAN_`` variables and some useful macros. - -The simplest way to consume it would be to invoke the ``conan_basic_setup()`` macro, which will basically -set global include directories, libraries directories, definitions, etc. so typically is enough to do: - -.. code-block:: cmake - - include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) - conan_basic_setup() - - add_executable(timer timer.cpp) - target_link_libraries(timer ${CONAN_LIBS}) - -The ``conan_basic_setup()`` is split in smaller macros, that should be self explanatory. If you need to do -something different, you can just use them individually. - -The above example is using the macro ``conan_global_flags()`` -which sets the global environment. For **modern cmake (>=3.1.2)**, the macro ``conan_define_targets()`` -defines cmake ``INTERFACE IMPORTED`` targets, one per package, so they can be used to link with, instead -of using global cmake setup. The name of the targets is ``CONAN_PKG::PackageName`` - -.. code-block:: cmake - - include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) - conan_basic_setup(TARGETS) - - add_executable(timer timer.cpp) - target_link_libraries(timer CONAN_PKG::Poco) - -CMake multi-configuration environments -======================================= - -There are environments, like Visual Studio and XCode IDEs that do not configure for a specific -``build_type``, like Debug or Release, but rather can be used for both and switch among Debug and -Release configurations with a combo box or similar control. The project configuration for cmake -is different, in multi-configuration environments, the flow would be: - -.. code-block:: bash - - $ cmake .. -G "Visual Studio 14 Win64" - # Now open the IDE (.sln file) or - $ cmake --build . --config Release - -While in single-configuration environments (Unix Makefiles, etc): - -.. code-block:: bash - - $ cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release - # Build from your IDE, launching make, or - $ cmake --build . - -The ``CMAKE_BUILD_TYPE`` default, if not specified is ``Debug``. - -With the regular conan ``cmake`` generator, only 1 configuration at a time can be managed. Then, -it is a universal, homogeneous solution for all environments. -This is the recommended way, using the regular ``cmake`` generator, and just go to the command line and -switch among configurations: - -.. code-block:: bash - - $ conan install -s build_type=Release -s compiler.runtime=MD ... - # Work in release, then, to switch to Debug dependencies - $ conan install -s build_type=Debug -s compiler.runtime=MDd ... - - -However, end consumers with heavy usage of the IDE, might want a multi-configuration build. The -``cmake_multi`` **experimental** generator is able to do that. First, both Debug and Release -dependencies have to be installed: - -.. code-block:: bash - - $ conan install -g cmake_multi -s build_type=Release -s compiler.runtime=MD ... - $ conan install -g cmake_multi -s build_type=Debug -s compiler.runtime=MDd ... - -These commands will generate 3 files: ``conanbuildinfo_release.cmake``, ``conanbuildinfo_debug.cmake``, -and ``conanbuildinfo_multi.cmake``, which includes the other two, and enables its use. - -The consumer project might write a ``CMakeLists.txt`` like: - -.. code-block:: cmake - - project(MyHello) - cmake_minimum_required(VERSION 2.8.12) - - include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake) - conan_basic_setup() - - add_executable(say_hello main.cpp) - foreach(_LIB ${CONAN_LIBS_RELEASE}) - target_link_libraries(say_hello optimized ${_LIB}) - endforeach() - foreach(_LIB ${CONAN_LIBS_DEBUG}) - target_link_libraries(say_hello debug ${_LIB}) - endforeach() - -Or, if using the modern cmake syntax with targets: - -.. code-block:: cmake - - project(MyHello) - cmake_minimum_required(VERSION 2.8.12) - - include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake) - conan_basic_setup(TARGETS) - - add_executable(say_hello main.cpp) - target_link_libraries(say_hello CONAN_PKG::Hello1) - -There's also a convenient macro for linking to all libraries: - -.. code-block:: cmake - - project(MyHello) - cmake_minimum_required(VERSION 2.8.12) - - include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake) - conan_basic_setup() - - add_executable(say_hello main.cpp) - conan_target_link_libraries(say_hello) - - -With this approach, the end user can open the generated IDE project and switch among both -configurations, building the project, or from the command line: - -.. code-block:: bash - - $ cmake --build . --config Release - # And without having to conan install again, or do anything else - $ cmake --build . --config Debug - -Build automation -================ - -You can invoke CMake from your conanfile.py file and automate the build of your library/project. -Conan provides a ``CMake()`` helper. This helper is useful to call ``cmake`` command both for creating conan packages -or automating your project build with the ``conan build`` command. The ``CMake()`` helper will take into account -your settings to automatically set definitions and a generator according to your compiler, build_type, etc. -Check the section :ref:`Building with CMake`. - - -Find Packages -============= - -If installed CMake already provides a FindXXX.cmake file for the library you are packaging, it should work automatically. - -Variables **CMAKE_INCLUDE_PATH** and **CMAKE_LIBRARY_PATH** are set with the right requirements paths. CMake **find_library** function will be able to locate the libraries in the package's folders. - -So, you can use **find_package** normally: - - -.. code-block:: cmake - - project(MyHello) - cmake_minimum_required(VERSION 2.8.12) - - include(conanbuildinfo.cmake) - conan_basic_setup() - - find_package("ZLIB") - - if(ZLIB_FOUND) - add_executable(enough enough.c) - include_directories(${ZLIB_INCLUDE_DIRS}) - target_link_libraries(enough ${ZLIB_LIBRARIES}) - else() - message(FATAL_ERROR "Zlib not found") - endif() - - -In addition to automatic **find_package** support, **CMAKE_MODULE_PATH** variable is set with your requirements root package paths. You can override the default behavior of any find_package() by creating a ``findXXX.cmake`` file in your package. - -Creating a custom FindXXX.cmake file ------------------------------------- - -Sometimes the "official" CMake FindXXX.cmake scripts are not ready to find our libraries (not supported library names for specific settings, fixed installation directories like C:\\OpenSSL... etc) -Or maybe there is no "official" CMake script for our library. - -So in these cases we can provide a custom **FindXXX.cmake** file in our conan packages: - -1. Create a file named FindXXX.cmake and save it in your conan package root folder. Where XXX is the name of the library that we will use in the **find_package** CMake function. -For example, we create a ``FindZLIB.cmake`` and use ``find_package(ZLIB)``. -We recommend (if exists) to copy the original FindXXX.cmake file from kitware if provided (folder Modules/FindXXX.cmake) and modify it to help finding our library files, but it depends a lot, maybe you are interested in create a new one. - -If it's not provided you can create a basic one, take a look to this example with the ZLIB library: - -**FindZLIB.cmake** - -.. code-block:: cmake - - find_path(ZLIB_INCLUDE_DIR NAMES zlib.h PATHS ${CONAN_INCLUDE_DIRS_ZLIB}) - find_library(ZLIB_LIBRARY NAMES ${CONAN_LIBS_ZLIB} PATHS ${CONAN_LIB_DIRS_ZLIB}) - - set(ZLIB_FOUND TRUE) - set(ZLIB_INCLUDE_DIRS ${ZLIB_INCLUDE_DIR}) - set(ZLIB_LIBRARIES ${ZLIB_LIBRARY}) - mark_as_advanced(ZLIB_LIBRARY ZLIB_INCLUDE_DIR) - - -In the first line we are finding the path where our headers should be found, we suggest the CONAN_INCLUDE_DIRS_XXX. -Then the same for the library names with CONAN_LIBS_XXX and the paths where the libs are CONAN_LIB_DIRS_XXX. - -2. In your conanfile.py file add the ``FindXXX.cmake`` to the ``exports_sources`` field: - - -.. code-block:: python - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - ... - exports_sources = ["FindXXX.cmake"] - -3. In the package method, copy the ``FindXXX.cmake`` file to the root: - - - -.. code-block:: python - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - ... - exports_sources = ["FindXXX.cmake"] - - - def package(self): - ... - self.copy("FindXXX.cmake", ".", ".") - - - -.. |cmake_logo| image:: ../images/cmake_logo.png - -.. _`conan's boost package`: https://github.com/lasote/conan-boost.git -.. _`conan's zlib package`: https://github.com/lasote/conan-zlib.git +.. |cmake_logo| image:: ../images/cmake_logo.png \ No newline at end of file diff --git a/integrations/cmake/build_automation.rst b/integrations/cmake/build_automation.rst new file mode 100644 index 000000000000..72ecce9babb2 --- /dev/null +++ b/integrations/cmake/build_automation.rst @@ -0,0 +1,11 @@ + +Build automation +================ + +You can invoke CMake from your conanfile.py file and automate the build of your library/project. +Conan provides a ``CMake()`` helper. This helper is useful to call ``cmake`` command both for creating conan packages +or automating your project build with the ``conan build`` command. The ``CMake()`` helper will take into account +your settings to automatically set definitions and a generator according to your compiler, build_type, etc. + + +.. seealso:: Check the section :ref:`Building with CMake`. diff --git a/integrations/cmake/cmake_generator.rst b/integrations/cmake/cmake_generator.rst new file mode 100644 index 000000000000..847ae9bbeab8 --- /dev/null +++ b/integrations/cmake/cmake_generator.rst @@ -0,0 +1,60 @@ + +``cmake`` generator +=================== + +If you are using *CMake* to build your project, you can use the *cmake* generator to manage all your requirements. +It creates a file named ``conanbuildinfo.cmake`` that can be imported from your *CMakeLists.txt*. + + +**conanfile.txt** + +.. code-block:: text + + ... + + [generators] + cmake + + +When **conan install** is executed, a file named ``conanbuildinfo.cmake`` is created. + +We can include ``conanbuildinfo.cmake`` in our project's ``CMakeLists.txt`` to manage our requirements. +The inclusion of ``conanbuildinfo.cmake`` doesn't alter cmake environment at all, it just provide ``CONAN_`` variables and some useful macros. + + +Global/Classic consume approach +------------------------------- + +The simplest way to consume it would be to invoke the ``conan_basic_setup()`` macro, which will basically +set global include directories, libraries directories, definitions, etc. so typically is enough to do: + +.. code-block:: cmake + + include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) + conan_basic_setup() + + add_executable(timer timer.cpp) + target_link_libraries(timer ${CONAN_LIBS}) + +The ``conan_basic_setup()`` is split in smaller macros, that should be self explanatory. If you need to do +something different, you can just use them individually. + + +Targets/Modern consume approach +------------------------------- + +For **modern cmake (>=3.1.2)**, the macro ``conan_define_targets()`` +defines cmake ``INTERFACE IMPORTED`` targets, one per package, so they can be used to link with, instead +of using global cmake setup. The name of the targets is ``CONAN_PKG::PackageName`` + +.. code-block:: cmake + + include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) + conan_basic_setup(TARGETS) + + add_executable(timer timer.cpp) + target_link_libraries(timer CONAN_PKG::Poco) + + +.. seealso:: Check the section :ref:`Reference/Generators/cmake ` to read more about this generator. + diff --git a/integrations/cmake/cmake_multi_generator.rst b/integrations/cmake/cmake_multi_generator.rst new file mode 100644 index 000000000000..14a28edede63 --- /dev/null +++ b/integrations/cmake/cmake_multi_generator.rst @@ -0,0 +1,114 @@ +``cmake_multi`` generator +========================= + + +``cmake_multi`` generator is intended for CMake multi-configuration environments, like Visual Studio and XCode IDEs that do not configure for a specific +``build_type``, like Debug or Release, but rather can be used for both and switch among Debug andRelease configurations with a combo box or similar control. +The project configuration for cmake is different, in multi-configuration environments, the flow would be: + +.. code-block:: bash + + $ cmake .. -G "Visual Studio 14 Win64" + # Now open the IDE (.sln file) or + $ cmake --build . --config Release + +While in single-configuration environments (Unix Makefiles, etc): + +.. code-block:: bash + + $ cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release + # Build from your IDE, launching make, or + $ cmake --build . + +The ``CMAKE_BUILD_TYPE`` default, if not specified is ``Debug``. + +With the regular conan ``cmake`` generator, only 1 configuration at a time can be managed. Then, +it is a universal, homogeneous solution for all environments. +This is the recommended way, using the regular ``cmake`` generator, and just go to the command line and +switch among configurations: + +.. code-block:: bash + + $ conan install -s build_type=Release -s compiler.runtime=MD ... + # Work in release, then, to switch to Debug dependencies + $ conan install -s build_type=Debug -s compiler.runtime=MDd ... + + +However, end consumers with heavy usage of the IDE, might want a multi-configuration build. The +``cmake_multi`` **experimental** generator is able to do that. First, both Debug and Release +dependencies have to be installed: + +.. code-block:: bash + + $ conan install -g cmake_multi -s build_type=Release -s compiler.runtime=MD ... + $ conan install -g cmake_multi -s build_type=Debug -s compiler.runtime=MDd ... + +These commands will generate 3 files: ``conanbuildinfo_release.cmake``, ``conanbuildinfo_debug.cmake``, +and ``conanbuildinfo_multi.cmake``, which includes the other two, and enables its use. + + +Global/Classic approach +----------------------- + +The consumer project might write a ``CMakeLists.txt`` like: + +.. code-block:: cmake + + project(MyHello) + cmake_minimum_required(VERSION 2.8.12) + + include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake) + conan_basic_setup() + + add_executable(say_hello main.cpp) + foreach(_LIB ${CONAN_LIBS_RELEASE}) + target_link_libraries(say_hello optimized ${_LIB}) + endforeach() + foreach(_LIB ${CONAN_LIBS_DEBUG}) + target_link_libraries(say_hello debug ${_LIB}) + endforeach() + + +Global/Classic approach +----------------------- + +Or, if using the modern cmake syntax with targets: + +.. code-block:: cmake + + project(MyHello) + cmake_minimum_required(VERSION 2.8.12) + + include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake) + conan_basic_setup(TARGETS) + + add_executable(say_hello main.cpp) + target_link_libraries(say_hello CONAN_PKG::Hello1) + +There's also a convenient macro for linking to all libraries: + +.. code-block:: cmake + + project(MyHello) + cmake_minimum_required(VERSION 2.8.12) + + include(${CMAKE_BINARY_DIR}/conanbuildinfo_multi.cmake) + conan_basic_setup() + + add_executable(say_hello main.cpp) + conan_target_link_libraries(say_hello) + + +With this approach, the end user can open the generated IDE project and switch among both +configurations, building the project, or from the command line: + +.. code-block:: bash + + $ cmake --build . --config Release + # And without having to conan install again, or do anything else + $ cmake --build . --config Debug + + + +.. seealso:: Check the section :ref:`Reference/Generators/cmake ` to read more about this generator.. + diff --git a/integrations/cmake/find_packages.rst b/integrations/cmake/find_packages.rst new file mode 100644 index 000000000000..d35b45f54ed4 --- /dev/null +++ b/integrations/cmake/find_packages.rst @@ -0,0 +1,94 @@ + +Find Packages +============= + +If installed CMake already provides a FindXXX.cmake file for the library you are packaging, it should work automatically. + +Variables **CMAKE_INCLUDE_PATH** and **CMAKE_LIBRARY_PATH** are set with the right requirements paths. CMake **find_library** function will be able to locate the libraries in the package's folders. + +So, you can use **find_package** normally: + + +.. code-block:: cmake + + project(MyHello) + cmake_minimum_required(VERSION 2.8.12) + + include(conanbuildinfo.cmake) + conan_basic_setup() + + find_package("ZLIB") + + if(ZLIB_FOUND) + add_executable(enough enough.c) + include_directories(${ZLIB_INCLUDE_DIRS}) + target_link_libraries(enough ${ZLIB_LIBRARIES}) + else() + message(FATAL_ERROR "Zlib not found") + endif() + + +In addition to automatic **find_package** support, **CMAKE_MODULE_PATH** variable is set with your requirements root package paths. You can override the default behavior of any find_package() by creating a ``findXXX.cmake`` file in your package. + +Creating a custom FindXXX.cmake file +------------------------------------ + +Sometimes the "official" CMake FindXXX.cmake scripts are not ready to find our libraries (not supported library names for specific settings, fixed installation directories like C:\\OpenSSL... etc) +Or maybe there is no "official" CMake script for our library. + +So in these cases we can provide a custom **FindXXX.cmake** file in our conan packages: + +1. Create a file named FindXXX.cmake and save it in your conan package root folder. Where XXX is the name of the library that we will use in the **find_package** CMake function. +For example, we create a ``FindZLIB.cmake`` and use ``find_package(ZLIB)``. +We recommend (if exists) to copy the original FindXXX.cmake file from kitware if provided (folder Modules/FindXXX.cmake) and modify it to help finding our library files, but it depends a lot, maybe you are interested in create a new one. + +If it's not provided you can create a basic one, take a look to this example with the ZLIB library: + +**FindZLIB.cmake** + +.. code-block:: cmake + + find_path(ZLIB_INCLUDE_DIR NAMES zlib.h PATHS ${CONAN_INCLUDE_DIRS_ZLIB}) + find_library(ZLIB_LIBRARY NAMES ${CONAN_LIBS_ZLIB} PATHS ${CONAN_LIB_DIRS_ZLIB}) + + set(ZLIB_FOUND TRUE) + set(ZLIB_INCLUDE_DIRS ${ZLIB_INCLUDE_DIR}) + set(ZLIB_LIBRARIES ${ZLIB_LIBRARY}) + mark_as_advanced(ZLIB_LIBRARY ZLIB_INCLUDE_DIR) + + +In the first line we are finding the path where our headers should be found, we suggest the CONAN_INCLUDE_DIRS_XXX. +Then the same for the library names with CONAN_LIBS_XXX and the paths where the libs are CONAN_LIB_DIRS_XXX. + +2. In your conanfile.py file add the ``FindXXX.cmake`` to the ``exports_sources`` field: + + +.. code-block:: python + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + ... + exports_sources = ["FindXXX.cmake"] + +3. In the package method, copy the ``FindXXX.cmake`` file to the root: + + + +.. code-block:: python + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + ... + exports_sources = ["FindXXX.cmake"] + + + def package(self): + ... + self.copy("FindXXX.cmake", ".", ".") + + + +.. _`conan's boost package`: https://github.com/lasote/conan-boost.git +.. _`conan's zlib package`: https://github.com/lasote/conan-zlib.git diff --git a/integrations/qbs.rst b/integrations/qbs.rst index 021876b32f88..d2bf4939297e 100644 --- a/integrations/qbs.rst +++ b/integrations/qbs.rst @@ -1,25 +1,13 @@ .. _qbs: -Qbs -_____________________ +qbs +____ -As of version 0.7 of conan, a Qbs generator is available -that can be configured as follows: - -**conanfile.txt** - -.. code-block:: text - - ... - - [generators] - qbs - -It will generate a ``conanbuildinfo.qbs`` file that can be used for your +Conan provides a **qbs** generator, it will generate a ``conanbuildinfo.qbs`` file that can be used for your qbs builds. -Add ``conanbuildinfo.qbs`` as a reference on the project level and a Depends -item with the name ``conanbuildinfo``: + +Add ``conanbuildinfo.qbs`` as a reference on the project level and a Depends item with the name ``conanbuildinfo``: **yourproject.qbs** @@ -70,62 +58,4 @@ You may also specify multiple dependencies: } -The contents of ``conanbuildinfo.qbs`` could look like this: - -**conanbuildinfo.qbs** - -.. code-block:: qbs - - import qbs 1.0 - - Project { - Product { - name: "ConanBasicSetup" - Export { - Depends { name: "cpp" } - cpp.includePaths: ["/home/username/.conan/data/hellopackage/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include", - "/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include"] - cpp.libraryPaths: ["/home/username/.conan/data/hellopackage/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib", - "/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib"] - cpp.systemIncludePaths: ["/home/username/.conan/data/hellopackage/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin", - "/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin"] - cpp.dynamicLibraries: ["hellopackage"] - cpp.defines: [] - cpp.cppFlags: [] - cpp.cFlags: [] - cpp.linkerFlags: [] - } - } - - Product { - name: "Catch" - Export { - Depends { name: "cpp" } - cpp.includePaths: ["/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include"] - cpp.libraryPaths: ["/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib"] - cpp.systemIncludePaths: ["/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin"] - cpp.dynamicLibraries: [] - cpp.defines: [] - cpp.cppFlags: [] - cpp.cFlags: [] - cpp.linkerFlags: [] - } - } - // Catch root path: /home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed - - Product { - name: "hellopackage" - Export { - Depends { name: "cpp" } - cpp.includePaths: ["/home/username/.conan/data/hellopackage/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include"] - cpp.libraryPaths: ["/home/username/.conan/data/hellopackage/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib"] - cpp.systemIncludePaths: ["/home/username/.conan/data/hellopackage/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin"] - cpp.dynamicLibraries: ["hellopackage"] - cpp.defines: [] - cpp.cppFlags: [] - cpp.cFlags: [] - cpp.linkerFlags: [] - } - } - // hellopackage root path: /home/username/.conan/data/hellopackage/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed - } +.. seealso:: Check the :ref:`Reference/Generators/qbs` section for get more details. \ No newline at end of file diff --git a/integrations/qmake.rst b/integrations/qmake.rst index 489ceac0f270..ec52ca86d3f3 100644 --- a/integrations/qmake.rst +++ b/integrations/qmake.rst @@ -4,22 +4,8 @@ QMake _____ -As of version 0.5 of conan, a qmake generator is available that can be -configured as follows: - -**conanfile.txt** - -.. code-block:: text - - ... - - [generators] - qmake - -It will generate a ``conanbuildinfo.pri`` file that can be used for your -qmake builds. -Add ``conan_basic_setup`` to ``CONFIG`` and include the file in your existing -.pro file: +A qmake generator will generate a ``conanbuildinfo.pri`` file that can be used for your qmake builds. +Add ``conan_basic_setup`` to ``CONFIG`` and include the file in your existing ``.pro`` file: **yourproject.pro** @@ -51,58 +37,5 @@ you can do so by skipping the CONFIG statement and only include # INCLUDEPATH += CONAN_INCLUDEPATH_POCO -The contents of ``conanbuildinfo.pri`` could look like this: - -**conanfile.pri** - -.. code-block:: text - - CONAN_INCLUDEPATH += /home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include \ - /home/username/.conan/data/hellolibrary/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include - CONAN_LIBS += -L/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib \ - -L/home/username/.conan/data/hellolibrary/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib - CONAN_BINDIRS += /home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin \ - /home/username/.conan/data/hellolibrary/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin - CONAN_LIBS += -lhellolibrary - CONAN_DEFINES += - CONAN_QMAKE_CXXFLAGS += - CONAN_QMAKE_CFLAGS += - CONAN_QMAKE_LFLAGS += - CONAN_QMAKE_LFLAGS += - - CONAN_INCLUDEPATH_CATCH += /home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include - CONAN_LIBS_CATCH += -L/home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib - CONAN_BINDIRS_CATCH += /home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin - CONAN_LIBS_CATCH += - CONAN_DEFINES_CATCH += - CONAN_QMAKE_CXXFLAGS_CATCH += - CONAN_QMAKE_CFLAGS_CATCH += - CONAN_QMAKE_LFLAGS_CATCH += - CONAN_QMAKE_LFLAGS_CATCH += - CONAN_CATCH_ROOT = /home/username/.conan/data/Catch/1.3.2/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed - - CONAN_INCLUDEPATH_HELLOLIBRARY += /home/username/.conan/data/hellolibrary/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/include - CONAN_LIBS_HELLOLIBRARY += -L/home/username/.conan/data/hellolibrary/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/lib - CONAN_BINDIRS_HELLOLIBRARY += /home/username/.conan/data/hellolibrary/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed/bin - CONAN_LIBS_HELLOLIBRARY += -lhellolibrary - CONAN_DEFINES_HELLOLIBRARY += - CONAN_QMAKE_CXXFLAGS_HELLOLIBRARY += - CONAN_QMAKE_CFLAGS_HELLOLIBRARY += - CONAN_QMAKE_LFLAGS_HELLOLIBRARY += - CONAN_QMAKE_LFLAGS_HELLOLIBRARY += - CONAN_HELLOLIBRARY_ROOT = /home/username/.conan/data/hellolibrary/0.1/maintainer/master/package/0692fb2bd888ba708ca65670557c56d2e16851ed - - CONFIG(conan_basic_setup) { - INCLUDEPATH += $$CONAN_INCLUDEPATH - LIBS += $$CONAN_LIBS - BINDIRS += $$CONAN_BINDIRS - LIBS += $$CONAN_LIBS - DEFINES += $$CONAN_DEFINES - QMAKE_CXXFLAGS += $$CONAN_QMAKE_CXXFLAGS - QMAKE_CFLAGS += $$CONAN_QMAKE_CFLAGS - QMAKE_LFLAGS += $$CONAN_QMAKE_LFLAGS - } +.. seealso:: Check the :ref:`Reference/Generators/qmake ` for the complete reference. -Note that both ``CONAN_INCLUDEPATH`` and dependency specific variables such as -``CONAN_INCLUDEPATH_POCO`` are defined so that you may choose to include all or -only some include paths for your requirements. diff --git a/integrations/visual_studio.rst b/integrations/visual_studio.rst index 525d1fa61a26..deb98967d69a 100644 --- a/integrations/visual_studio.rst +++ b/integrations/visual_studio.rst @@ -4,9 +4,6 @@ |visual_logo| Visual Studio ================================= - - - Conan can be integrated with **Visual Studio** in two different ways: - Using the **cmake** generator to create a **conanbuildinfo.cmake** file. @@ -25,9 +22,7 @@ Check the official `CMake docs`_ to find out more about generating Visual Studio With *visual_studio* generator ------------------------------ - - -You can use the **visual_studio** :ref:`generator` to manage your requirements via your *Visual Studio* project. +You can use the **visual_studio** generator to manage your requirements via your *Visual Studio* project. .. |visual_logo| image:: ../images/visual-studio-logo.png @@ -70,7 +65,11 @@ Build your project as usual. If these values don't match, you build will probably fail. e.g. **Release/x64** - + + +.. seealso:: Check the :ref:`Reference/Generators/visual_studio ` for the complete reference. + + Calling Visual Studio compiler ------------------------------ @@ -89,4 +88,6 @@ Build an existing Visual Studio project You can build an existing Visual Studio from your ``build()`` method using the ``tools.build_sln_command``. -Check the :ref:`tools.build_sln_command()` reference section for more info. + +.. seealso:: Check the :ref:`tools.build_sln_command()` reference section for more info. + diff --git a/integrations/xcode.rst b/integrations/xcode.rst index 3cf337acd13a..9084881279cc 100644 --- a/integrations/xcode.rst +++ b/integrations/xcode.rst @@ -14,7 +14,7 @@ Conan can be integrated with **XCode** in two different ways: With CMake ---------- -Check the :ref:`generator` section to read about the **cmake** generator. +Check the :ref:`Integrations/cmake` section to read about the **cmake** generator. Check the official `CMake docs`_ to find out more about generating Xcode projects with CMake. @@ -23,20 +23,13 @@ Check the official `CMake docs`_ to find out more about generating Xcode project With the *xcode* generator -------------------------- -You can use the **xcode** :ref:`generator` to integrate your requirements in your *Xcode* project. +You can use the **xcode** generator to integrate your requirements in your *Xcode* project. This generator creates an ``xcconfig`` file, with all the *include paths*, *lib paths*, *libs*, *flags* etc, that can be imported in your project. .. |xcode_logo| image:: ../images/xcode_logo.jpg - - - - - - - Open ``conanfile.txt`` and change (or add) the **xcode** generator: @@ -67,3 +60,9 @@ Click on the project again. In the **info/configurations** section, choose **con .. image:: ../images/xcode3.png Build your project as usual. + + + +.. seealso:: Check the :ref:`Reference/Generators/xcode ` for the complete reference. + + diff --git a/manage_deps/conanfile_txt.rst b/manage_deps/conanfile_txt.rst index 4b5af1b0058d..c6d673d83066 100644 --- a/manage_deps/conanfile_txt.rst +++ b/manage_deps/conanfile_txt.rst @@ -82,35 +82,12 @@ Other example could be, in order to try out some new zlib alpha features, we cou Generators .......... -Conan reads the **[generators]** section from ``conanfile.txt`` and creates files for each generator with all the necessary information to link your program with the specified requirements. The generated files are usually temporary, created in build folders and not committed to version control, as they have paths to local folder that will not exist in another machin. Also, it is very important to highlight that generated files match the given configuration (Debug/Release, x86/x86_64, etc), specified at ``conan install`` time. If the configuration changes, the files will change. +Conan reads the **[generators]** section from ``conanfile.txt`` and creates files for each generator with all the necessary information to link your program with the specified requirements. +The generated files are usually temporary, created in build folders and not committed to version control, as they have paths to local folder that will not exist in another machine. +Also, it is very important to highlight that generated files match the given configuration (Debug/Release, x86/x86_64, etc), +specified at ``conan install`` time. If the configuration changes, the files will change. - -*cmake* -_______ - -The **cmake** generator creates a file named ``conanbuildinfo.cmake`` that can be imported from your *CMakeLists.txt*. -Check the section :ref:`Integrations/CMake ` to read more about this generator. - - -*visual_studio* -_______________ - -The **visual_studio** generator creates a file named ``conanbuildinfo.props`` that can be imported to your *Visual Studio* project. -Check the section :ref:`Integrations/Visual Studio` to read more about this generator. - - -*xcode* -_______ - -The **xcode** generator creates a file named ``conanbuildinfo.xcconfig`` that can be imported to your *XCode* project. -Check the section :ref:`Integrations/XCode ` to read more about this generator. - -*other* -_______ - -There are some other generators, check them in :ref:`Integrations `. You might -use the generic :ref:`text generator `, or maybe even -:ref:`create and share a new generator ` +Check the complete :ref:`generators` reference. Options diff --git a/mastering.rst b/mastering.rst index 4d642c4f79ca..44a011966ea4 100644 --- a/mastering.rst +++ b/mastering.rst @@ -12,8 +12,8 @@ This section provides an introduction to important productivity features and use mastering/profiles mastering/build mastering/conditional - mastering/run mastering/scopes mastering/policies mastering/envvars + mastering/virtualenv mastering/logging diff --git a/mastering/build.rst b/mastering/build.rst index 604533dc7e36..a88f538d5040 100644 --- a/mastering/build.rst +++ b/mastering/build.rst @@ -1,13 +1,19 @@ Build helpers -================== +============= + There are several helpers that can assist to automate the ``build()`` method for popular build systems: .. _building_with_cmake: CMake ------------------ +----- + +The `CMake` class help us to invoke `cmake` command with the generator, flags and definitions, reflecting the specified Conan settings. + -The CMake class has two properties ``command_line`` and ``build_config`` to help running cmake commands: +There are two ways to invoke your cmake tools: + +- Using the helper attributes ``cmake.command_line`` and ``cmake.build_config``: .. code-block:: python @@ -16,48 +22,32 @@ The CMake class has two properties ``command_line`` and ``build_config`` to help self.run('cmake "%s" %s' % (self.conanfile_directory, cmake.command_line)) self.run('cmake --build . %s' % cmake.build_config) -They will set up flags and a cmake generator that reflects the specified Conan settings. However the two methods ``configure()`` and ``build()`` operate with cmake on a higher level: -CMake.configure() -++++++++++++++++++++ -The ``cmake`` invocation in the configuration step is highly customizable: +- Using the helper methods: .. code-block:: python - CMake.configure(self, conan_file, args=None, defs=None, source_dir=None, build_dir=None) - - -- ``conan_file`` is the ConanFile to use and read settings from. Typically ``self`` is passed -- ``args`` is a list of additional arguments to be passed to the ``cmake`` command. Each argument will be escaped according to the current shell. No extra arguments will be added if ``args=None`` -- ``defs`` is a dict that will be converted to a list of CMake command line variable definitions of the form ``-DKEY=VALUE``. Each value will be escaped according to the current shell and can be either ``str``, ``bool`` or of numeric type -- ``source_dir`` is CMake's source directory where ``CMakeLists.txt`` is located. The default value is ``conan_file.conanfile_directory`` if ``None`` is specified. Relative paths are allowed and will be relative to ``build_dir`` -- ``build_dir`` is CMake's output directory. The default value is ``conan_file.conanfile_directory`` if ``None`` is specified. The ``CMake`` object will store ``build_dir`` internally for subsequent calls to ``build()`` - -CMake.build() -++++++++++++++++++++ - -.. code-block:: python + def build(self): + cmake = CMake(self.settings) + cmake.configure(self, source_dir=self.conanfile_directory, build_dir="./") + cmake.build(self) - CMake.build(self, conan_file, args=None, build_dir=None, target=None) -- ``conan_file`` is the ``ConanFile`` to use and read settings from. Typically ``self`` is passed -- ``args`` is a list of additional arguments to be passed to the ``cmake`` command. Each argument will be escaped according to the current shell. No extra arguments will be added if ``args=None`` -- ``build_dir`` is CMake's output directory. If ``None`` is specified the ``build_dir`` from ``configure()`` will be used. ``conan_file.conanfile_directory`` is used if ``configure()`` has not been called -- ``target`` specifies the target to execute. The default *all* target will be built if ``None`` is specified. ``"install"`` can be used to relocate files to aid packaging +.. seealso:: Check the section :ref:`Reference/Build Helpers/CMake ` to find out more. .. _building_with_autotools: Autotools: configure / make ----------------------------------- +--------------------------- If you are using **configure**/**make** you can use **AutoToolsBuildEnvironment** helper. This helper sets ``LIBS``, ``LDFLAGS``, ``CFLAGS``, ``CXXFLAGS`` and ``CPPFLAGS`` environment variables based on your requirements. -It works using the *environment_append* context manager applied to your **configure and make** commands: +It works using the :ref:`environment_append ` context manager applied to your **configure and make** commands: .. code-block:: python :emphasize-lines: 13, 14 @@ -83,7 +73,7 @@ It works using the *environment_append* context manager applied to your **config For Windows users: - It also works with **nmake**. - - If you have ``MSYS2``/``MinGW`` installed and in the PATH you take advantage of the ``tool.run_in_windows_bash`` command: + - If you have ``MSYS2``/``MinGW`` installed and in the PATH you take advantage of the :ref:`tools.run_in_windows_bash_tool ` command: .. code-block:: python @@ -113,32 +103,8 @@ For Windows users: self._run_cmd("make") -The ``AutoToolsBuildEnvironment`` lets to adjust some variables before calling the `vars` method, so you can -add or change some default value automatically filled: - -+-----------------------------+---------------------------------------------------------------------+ -| PROPERTY | DESCRIPTION | -+=============================+=====================================================================+ -| .fpic | Boolean, Set it to True if you want to append the -fPIC flag | -+-----------------------------+---------------------------------------------------------------------+ -| .libs | List with library names of the requirements (-l in LIBS) | -+-----------------------------+---------------------------------------------------------------------+ -| .include_paths | List with the include paths of the requires (-I in CPPFLAGS) | -+-----------------------------+---------------------------------------------------------------------+ -| .library_paths | List with library paths of the requirements (-L in LDFLAGS) | -+-----------------------------+---------------------------------------------------------------------+ -| .defines | List with variables that will be defined with -D in CPPFLAGS | -+-----------------------------+---------------------------------------------------------------------+ -| .flags | List with compilation flags (CFLAGS and CXXFLAGS) | -+-----------------------------+---------------------------------------------------------------------+ -| .cxx_flags | List with only c++ compilation flags (CXXFLAGS) | -+-----------------------------+---------------------------------------------------------------------+ -| .link_flags | List with linker flags | -+-----------------------------+---------------------------------------------------------------------+ - - -Example: - +You can change some variables like ``.fpic``, ``.libs``, ``.include_paths``, ``defines`` before accessing the ``vars`` to override +an automatic value or add new values: .. code-block:: python :emphasize-lines: 8, 9, 10 @@ -159,35 +125,9 @@ Example: self.run("make") -Set environment variables: - -+--------------------+---------------------------------------------------------------------+ -| NAME | DESCRIPTION | -+====================+=====================================================================+ -| LIBS | Library names to link | -+--------------------+---------------------------------------------------------------------+ -| LDFLAGS | Link flags, (-L, -m64, -m32) | -+--------------------+---------------------------------------------------------------------+ -| CFLAGS | Options for the C compiler (-g, -s, -m64, -m32, -fPIC) | -+--------------------+---------------------------------------------------------------------+ -| CXXFLAGS | Options for the C++ compiler (-g, -s, -stdlib, -m64, -m32, -fPIC) | -+--------------------+---------------------------------------------------------------------+ -| CPPFLAGS | Preprocessor definitions (-D, -I) | -+--------------------+---------------------------------------------------------------------+ - - -.. note:: +.. seealso:: Check the :ref:`Reference/Build Helpers/AutoToolsBuildEnvironment ` to see the complete reference. - **ConfigureEnvironment** helper class has been deprecated. It was used to: - - 1. Create a command line command to declare the environment variables inherited from the requirements (self.deps_env_info): - - This is not needed anymore, the environment variables inherited from the requirements ``self.deps_env_info`` objects are automatically set before the ``source``, ``build``, ``package`` and ``imports`` methods. See the section above. - - 2. Create a command line to set environment variables before calling the build system, usually before calling ``configure`` or ``make``: - - The new ``AutoToolsBuildEnvironment`` and ``VisualStudioBuildEnvironment`` with the ``tool.environment_append`` offers cleaner and more flexible solution. .. _building_with_visual_studio: @@ -217,16 +157,8 @@ Example: self.run('%s && cl /c /EHsc hello.cpp' % vcvars) self.run('%s && lib hello.obj -OUT:hello.lib' % vcvars +.. seealso:: Check the :ref:`Reference/Build Helpers/VisualStudioBuildEnvironment ` to see the complete reference. -Set environment variables: - -+--------------------+---------------------------------------------------------------------+ -| NAME | DESCRIPTION | -+====================+=====================================================================+ -| LIB | Library paths separated with ";" | -+--------------------+---------------------------------------------------------------------+ -| CL | "/I" flags with include directories | -+--------------------+---------------------------------------------------------------------+ .. _building_with_gcc_clang: @@ -256,3 +188,41 @@ It's valid to invoke both gcc and clang compilers. self.run("mkdir -p bin") command = 'g++ timer.cpp @conanbuildinfo.gcc -o bin/timer' self.run(command) + + + +.. seealso:: Check the :ref:`Reference/Generators/gcc ` for the complete reference. + + + +RunEnvironment +-------------- + +The ``RunEnvironment`` helper prepare ``PATH``, ``LD_LIBRARY_PATH`` and ``DYLIB_LIBRARY_PATH`` environment variables to locate shared libraries and executables of your requirements at runtime. + +This helper is specially useful: + +- If you are requiring packages with shared libraries and you are running some executable that needs those libraries. +- If you have a requirement with some tool (executable) and you need it in the path. + + +Example: + + +.. code-block:: python + :emphasize-lines: 7, 8, 9 + + from conans import ConanFile, AutoToolsBuildEnvironment + + class ExampleConan(ConanFile): + ... + + def build(self): + env_build = RunEnvironment(self) + with tools.environment_append(env_build.vars): + self.run("....") + # All the requirements bin folder will be available at PATH + # All the lib folders will be available in LD_LIBRARY_PATH and DYLIB_LIBRARY_PATH + +.. seealso:: Check the :ref:`Reference/Build Helpers/RunEnvironment ` to see the complete reference. + diff --git a/mastering/conanfile_py.rst b/mastering/conanfile_py.rst index d11a9eb8065b..38712e608f7f 100644 --- a/mastering/conanfile_py.rst +++ b/mastering/conanfile_py.rst @@ -120,4 +120,7 @@ Conan implements other commands that can be executed locally over a consumer ``c - ``conan source ``: Execute locally the conanfile.py ``source()`` method - ``conan package ``: Execute locally the conanfile.py ``package()`` method -These commands are mostly used for testing and debugging while developing a new package, before ``export-ing`` such package recipe into the local cache. \ No newline at end of file +These commands are mostly used for testing and debugging while developing a new package, before ``export-ing`` such package recipe into the local cache. + + +.. seealso:: Check the section :ref:`Reference/Commands` to find out more. \ No newline at end of file diff --git a/mastering/conditional.rst b/mastering/conditional.rst index 141dd9600129..3a69696c5a25 100644 --- a/mastering/conditional.rst +++ b/mastering/conditional.rst @@ -33,4 +33,7 @@ Here is an example of what we could do in our **configure method**: if self.options.testing: self.requires("OpenSSL/2.1@memsharded/testing") else: - self.requires("OpenSSL/1.0.2d@lasote/stable") \ No newline at end of file + self.requires("OpenSSL/1.0.2d@lasote/stable") + + +.. seealso:: Check the section :ref:`Reference/conanfile.py/configure(), config_options() ` to find out more. \ No newline at end of file diff --git a/mastering/profiles.rst b/mastering/profiles.rst index 21d506e0ed08..ae04a7098b4e 100644 --- a/mastering/profiles.rst +++ b/mastering/profiles.rst @@ -1,3 +1,6 @@ +.. _profiles: + + Profiles ========= @@ -5,7 +8,31 @@ So far we have used the default settings stored in ``conan.conf`` and defined as However, configurations can be large, settings can be very different, and we might want to switch easily between different configurations with different settings, options, etc. -Profiles are text files, that can be stored in different locations, as for example the default ``/.conan/profiles`` folder. +Profiles can be located in different folders, as for example the default ``/.conan/profiles``, and be referenced by absolute or relative path: + +.. code-block:: bash + + $ conan install --profile /abs/path/to/profile # abs path + $ conan install --profile ./relpath/to/profile # resolved to current dir + $ conan install --profile profile # resolved to user/.conan/profiles/profile + + +A profile file contains a predefined set of ``settings``, ``options``, ``environment variables``` and ``scopes`` and has this structure: + +.. code-block:: text + + [settings] + setting=value + + [options] + MyLib:shared=True + + [env] + env_var=value + + [scopes] + scope=value + They would contain the desired configuration, for example assume the following file is named ``myprofile``: @@ -40,4 +67,93 @@ You can list and show existing profiles with the ``conan profile`` command: $ conan profile show myprofile1 > Profile myprofile1 > [settings] - > ... \ No newline at end of file + > ... + +You can use ``$PROFILE_DIR`` in your profile and it will be replaced with the absolute path to the profile file. +It is useful to declare relative folders: + +.. code-block:: text + + [env] + PYTHONPATH=$PROFILE_DIR/my_python_tools + + +Package settings and env vars +----------------------------- + +Profiles also support **package settings** and **package environment variables** definition, so you can override some settings or env vars for some specific package: + + +- Create a ``.conan/profiles/zlib_with_clang`` file: + +.. code-block:: text + + [settings] + zlib:compiler=clang + zlib:compiler.version=3.5 + zlib:compiler.libcxx=libstdc++11 + compiler=gcc + compiler.version=4.9 + compiler.libcxx=libstdc++11 + + [env] + zlib:CC=/usr/bin/clang + zlib:CXX=/usr/bin/clang++ + +- Your build tool will locate **clang** compiler only for the **zlib** package and **gcc** (default one) for the rest of your dependency tree. + + + +Examples +-------- + +If you are working with Linux and you usually work with ``gcc`` compiler, but you have installed ``clang`` +compiler and want to install some package for ``clang`` compiler, you could do: + +- Create a ``.conan/profiles/clang`` file: + +.. code-block:: text + + [settings] + compiler=clang + compiler.version=3.5 + compiler.libcxx=libstdc++11 + + [env] + CC=/usr/bin/clang + CXX=/usr/bin/clang++ + + +- Execute conan install command passing the ``--profile`` or ``-pr`` parameter: + + +.. code-block:: bash + + conan install --profile clang + + + +Without profiles you would have needed to set the CC and CXX variables in the environment to point to your clang compiler and use ``-s`` parameters to specify the settings: + + +.. code-block:: bash + + export CC=/usr/bin/clang + export CXX=/usr/bin/clang++ + conan install -s compiler=clang -s compiler.version=3.5 -s compiler.libcxx=libstdc++11 + + +A profile can also be used in ``conan test_package`` and ``info`` command: + +.. code-block:: bash + + $ conan test_package --profile clang + + + + + +.. seealso:: - :ref:`Howtos/Cross Building ` + - :ref:`Reference/Commands/conan profile ` + - :ref:`Reference/Commands/conan install ` + - :ref:`Reference/Commands/conan test_package ` \ No newline at end of file diff --git a/integrations/virtualenv.rst b/mastering/virtualenv.rst similarity index 95% rename from integrations/virtualenv.rst rename to mastering/virtualenv.rst index 889e45bc0f63..2191eb72d360 100644 --- a/integrations/virtualenv.rst +++ b/mastering/virtualenv.rst @@ -4,6 +4,16 @@ Virtual Environments ==================== +!!! + +Conan virtual environments are special conan generators that b + +Concatenables + + +Listado, y para que sirve, y linkar a reference/generators + + Virtualenv generator -------------------- diff --git a/reference.rst b/reference.rst index 3a009ef4ae43..8257105485fa 100644 --- a/reference.rst +++ b/reference.rst @@ -8,14 +8,13 @@ General information about the commands, configuration files, etc. Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 3 reference/commands + reference/conanfile_txt reference/conanfile + reference/generators + reference/build_helpers + reference/tools reference/config_files reference/env_vars - reference/tools - - - - diff --git a/reference/build_helpers.rst b/reference/build_helpers.rst new file mode 100644 index 000000000000..e0c9243a15ae --- /dev/null +++ b/reference/build_helpers.rst @@ -0,0 +1,16 @@ +.. _build_helpers: + +Build helpers +============= + +There are several helpers that can assist to automate the build() method for popular build systems + +Contents: + +.. toctree:: + :maxdepth: 2 + + build_helpers/cmake + build_helpers/autotools + build_helpers/visual_studio + build_helpers/run_environment diff --git a/reference/build_helpers/autotools.rst b/reference/build_helpers/autotools.rst new file mode 100644 index 000000000000..fa5d98fa7b06 --- /dev/null +++ b/reference/build_helpers/autotools.rst @@ -0,0 +1,81 @@ +.. _autotools_reference: + + +AutoToolsBuildEnvironment +========================= + +Prepares the needed environment variables to invoke **configure**/**make**: + +.. code-block:: python + + def build(self): + env_build = AutoToolsBuildEnvironment(self) + with tools.environment_append(env_build.vars): + self.run("./configure") + self.run("make") + + +**Set environment variables** + ++--------------------+---------------------------------------------------------------------+ +| NAME | DESCRIPTION | ++====================+=====================================================================+ +| LIBS | Library names to link | ++--------------------+---------------------------------------------------------------------+ +| LDFLAGS | Link flags, (-L, -m64, -m32) | ++--------------------+---------------------------------------------------------------------+ +| CFLAGS | Options for the C compiler (-g, -s, -m64, -m32, -fPIC) | ++--------------------+---------------------------------------------------------------------+ +| CXXFLAGS | Options for the C++ compiler (-g, -s, -stdlib, -m64, -m32, -fPIC) | ++--------------------+---------------------------------------------------------------------+ +| CPPFLAGS | Preprocessor definitions (-D, -I) | ++--------------------+---------------------------------------------------------------------+ + + +**Attributes** + ++-----------------------------+---------------------------------------------------------------------+ +| PROPERTY | DESCRIPTION | ++=============================+=====================================================================+ +| .fpic | Boolean, Set it to True if you want to append the -fPIC flag | ++-----------------------------+---------------------------------------------------------------------+ +| .libs | List with library names of the requirements (-l in LIBS) | ++-----------------------------+---------------------------------------------------------------------+ +| .include_paths | List with the include paths of the requires (-I in CPPFLAGS) | ++-----------------------------+---------------------------------------------------------------------+ +| .library_paths | List with library paths of the requirements (-L in LDFLAGS) | ++-----------------------------+---------------------------------------------------------------------+ +| .defines | List with variables that will be defined with -D in CPPFLAGS | ++-----------------------------+---------------------------------------------------------------------+ +| .flags | List with compilation flags (CFLAGS and CXXFLAGS) | ++-----------------------------+---------------------------------------------------------------------+ +| .cxx_flags | List with only c++ compilation flags (CXXFLAGS) | ++-----------------------------+---------------------------------------------------------------------+ +| .link_flags | List with linker flags | ++-----------------------------+---------------------------------------------------------------------+ + + + +You can adjust the automatically filled values modifying the attributes above: + + +.. code-block:: python + :emphasize-lines: 8, 9, 10 + + from conans import ConanFile, AutoToolsBuildEnvironment + + class ExampleConan(ConanFile): + ... + + def build(self): + env_build = AutoToolsBuildEnvironment(self) + env_build.fpic = True + env_build.libs.append("pthread") + env_build.defines.append("NEW_DEFINE=23") + + with tools.environment_append(env_build.vars): + self.run("./configure") + self.run("make") + + +.. seealso:: - :ref:`Reference/Tools/environment_append ` \ No newline at end of file diff --git a/reference/build_helpers/cmake.rst b/reference/build_helpers/cmake.rst new file mode 100644 index 000000000000..a5e140e03dd6 --- /dev/null +++ b/reference/build_helpers/cmake.rst @@ -0,0 +1,74 @@ +.. _cmake_reference: + + +CMake +===== + +Invoke `cmake` explicitly with the helper ``command_line`` and ``build_config`` attributes: + +.. code-block:: python + + def build(self): + cmake = CMake(self.settings) + self.run('cmake "%s" %s' % (self.conanfile_directory, cmake.command_line)) + self.run('cmake --build . %s' % cmake.build_config) + + +Using the helper methods: + + +.. code-block:: python + + def build(self): + cmake = CMake(self.settings) + cmake.configure(self, source_dir=self.conanfile_directory, build_dir="./") + cmake.build(self) + + +Constructor +----------- + +CMake(settings, generator=None, cmake_system_name=True, parallel=True) + +- **settings**: Settings object. Usually ``self.settings`` in a conanfile.py +- **generator**: Specify a custom generator instead of autodetect it. e.j: "MinGW Makefiles" +- **cmake_system_name**: Specify a custom value for ``CMAKE_SYSTEM_NAME`` instead of autodetect it. +- **paralell**: If true, will append the `-jN` attribute for parallel building being N the :ref:`cpu_count()` + + + +Attributes +---------- + +- **command_line** (read only): Generator, conan definitions and flags that reflects the specified Conan settings. + +.. code-block:: text + + -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Release ... -DCONAN_C_FLAGS=-m64 -Wno-dev + +- **build_config** (read only): Value for ``--config`` option for Multi-configuration IDEs. + +.. code-block:: text + + --config Release + + +Methods +------- + +- **configure** (conan_file, args=None, defs=None, source_dir=None, build_dir=None) + + - **conan_file**: The ConanFile to use and read settings from. Typically ``self`` is passed + - **args**: A list of additional arguments to be passed to the ``cmake`` command. Each argument will be escaped according to the current shell. No extra arguments will be added if ``args=None`` + - **defs**: A dict that will be converted to a list of CMake command line variable definitions of the form ``-DKEY=VALUE``. Each value will be escaped according to the current shell and can be either ``str``, ``bool`` or of numeric type + - **source_dir**: CMake's source directory where ``CMakeLists.txt`` is located. The default value is ``conan_file.conanfile_directory`` if ``None`` is specified. Relative paths are allowed and will be relative to ``build_dir`` + - **build_dir**: CMake's output directory. The default value is ``conan_file.conanfile_directory`` if ``None`` is specified. The ``CMake`` object will store ``build_dir`` internally for subsequent calls to ``build()`` + +- **build** (conan_file, args=None, build_dir=None, target=None) + + - **conan_file**: The ``ConanFile`` to use and read settings from. Typically ``self`` is passed + - **args**: A list of additional arguments to be passed to the ``cmake`` command. Each argument will be escaped according to the current shell. No extra arguments will be added if ``args=None`` + - **build_dir**: CMake's output directory. If ``None`` is specified the ``build_dir`` from ``configure()`` will be used. ``conan_file.conanfile_directory`` is used if ``configure()`` has not been called + - **target**: Specifies the target to execute. The default *all* target will be built if ``None`` is specified. ``"install"`` can be used to relocate files to aid packaging + + diff --git a/mastering/run.rst b/reference/build_helpers/run_environment.rst similarity index 53% rename from mastering/run.rst rename to reference/build_helpers/run_environment.rst index 8720dec364db..aa4fb5a655e0 100644 --- a/mastering/run.rst +++ b/reference/build_helpers/run_environment.rst @@ -1,8 +1,21 @@ -Runtime dependencies and execution -==================================== -The ``RunEnvironment`` helper prepare some environment variables to locate shared libraries and executables of your requirements at runtime: +.. _run_environment_reference: +RunEnvironment +============== + +Prepares the needed environment variables to locate shared libraries and executables of your requirements at runtime. + +.. code-block:: python + :emphasize-lines: 7, 8, 9 + + def build(self): + env_build = RunEnvironment(self) + with tools.environment_append(env_build.vars): + self.run("....") + + +Set environment variables: +--------------------+---------------------------------------------------------------------+ | NAME | DESCRIPTION | @@ -15,33 +28,4 @@ The ``RunEnvironment`` helper prepare some environment variables to locate share +--------------------+---------------------------------------------------------------------+ -This helper is specially useful: - -- If you are requiring packages with shared libraries and you are running some executable that needs those libraries. -- If you have a requirement with some tool (executable) and you need it in the path. - - -Example: - - -.. code-block:: python - :emphasize-lines: 7, 8, 9 - - from conans import ConanFile, AutoToolsBuildEnvironment - - class ExampleConan(ConanFile): - ... - - def build(self): - env_build = RunEnvironment(self) - with tools.environment_append(env_build.vars): - self.run("....") - # All the requirements bin folder will be available at PATH - # All the lib folders will be available in LD_LIBRARY_PATH and DYLIB_LIBRARY_PATH - - -Runtime generators --------------------- - -- virtualenv -- virtualrunenv \ No newline at end of file +.. seealso:: - :ref:`Reference/Tools/environment_append ` \ No newline at end of file diff --git a/reference/build_helpers/visual_studio.rst b/reference/build_helpers/visual_studio.rst new file mode 100644 index 000000000000..ba747b6c1d13 --- /dev/null +++ b/reference/build_helpers/visual_studio.rst @@ -0,0 +1,33 @@ +.. _visual_studio_build_environment: + + +VisualStudioBuildEnvironment +============================ + +Prepares the needed environment variables to invoke the Visual Studio compiler: + +.. code-block:: python + :emphasize-lines: 3, 4, 5 + + def build(self): + if self.settings.compiler == "Visual Studio": + env_build = VisualStudioBuildEnvironment(self) + with tools.environment_append(env_build.vars): + vcvars = tools.vcvars_command(self.settings) + self.run('%s && cl /c /EHsc hello.cpp' % vcvars) + self.run('%s && lib hello.obj -OUT:hello.lib' % vcvars + + +Set environment variables: + ++--------------------+---------------------------------------------------------------------+ +| NAME | DESCRIPTION | ++====================+=====================================================================+ +| LIB | Library paths separated with ";" | ++--------------------+---------------------------------------------------------------------+ +| CL | "/I" flags with include directories | ++--------------------+---------------------------------------------------------------------+ + + + +.. seealso:: - :ref:`Reference/Tools/environment_append ` \ No newline at end of file diff --git a/reference/commands.rst b/reference/commands.rst index 0bf657a9d77a..6073fff2a238 100644 --- a/reference/commands.rst +++ b/reference/commands.rst @@ -1,1239 +1,28 @@ .. _commands: - Commands ======== - -conan export ------------- - -.. code-block:: bash - - $ conan export [-h] [--path PATH] [--keep-source] user - -Copies the package recipe (conanfile.py and associated files) to your local cache. -From the local cache it can be shared and reused in other projects. -Also, from the local cache, it can be uploaded to any remote with the "upload" command. - - -.. code-block:: bash - - - positional arguments: - user user_name[/channel]. By default, channel is "testing", - e.g., phil or phil/stable - - optional arguments: - --path PATH, -p PATH Optional. Folder with a conanfile.py. Default current - directory. - --keep-source, -k Optional. Do not remove the source folder in the local - cache. Use for testing purposes only - - - - -**Examples** - - -- Export a recipe from the current directory, under the ``myuser/testing`` user and channel: - -.. code-block:: bash - - $ conan export myuser - - -- Export a recipe from any folder directory, under the ``myuser/stable`` user and channel: - -.. code-block:: bash - - $ conan export ./folder_name myuser/stable - - -- Export a recipe without removing the source folder in the local cache: - -.. code-block:: bash - - $ conan export fenix/stable -k - - - -conan install -------------- - -.. code-block:: bash - - $ conan install [-h] [--package PACKAGE] [--all] [--file FILE] [--update] - [--scope SCOPE] [--profile PROFILE] - [--generator GENERATOR] [--werror] - [--manifests [MANIFESTS]] - [--manifests-interactive [MANIFESTS_INTERACTIVE]] - [--verify [VERIFY]] [--no-imports] [-r REMOTE] - [--options OPTIONS] [--settings SETTINGS] [--env ENV] - [--build [BUILD [BUILD ...]]] - [reference] - - - -Installs the requirements specified in a ``conanfile.py`` or ``conanfile.txt``. -It can also be used to install a concrete recipe/package specified by the ``reference`` parameter. -If the recipe is not found in the local cache it will retrieve the recipe from a remote, looking -for it sequentially in the available configured remotes. -When the recipe has been downloaded it will try to download a binary package matching the specified settings, -only from the remote from which the recipe was retrieved. -If no binary package is found you can build the package from sources using the ``--build`` option. - - -.. code-block:: bash - - - positional arguments: - reference package recipe reference, e.g. MyPackage/1.2@user/channel or ./my_project/ - - optional arguments: - --package PACKAGE, -p PACKAGE - Force install specified package ID (ignore settings/options) - --all Install all packages from the specified package recipe - --file FILE, -f FILE specify conanfile filename - --update, -u update with new upstream packages, overwriting the local cache if needed. - --scope SCOPE, -sc SCOPE - Use the specified scope in the install command - --profile PROFILE, -pr PROFILE - Apply the specified profile to the install command - --generator GENERATOR, -g GENERATOR - Generators to use - --werror Error instead of warnings for graph inconsistencies - --manifests [MANIFESTS], -m [MANIFESTS] - Install dependencies manifests in folder for later verify. - Default folder is .conan_manifests, but can be changed. - --manifests-interactive [MANIFESTS_INTERACTIVE], -mi [MANIFESTS_INTERACTIVE] - Install dependencies manifests in folder for later verify, asking user for - confirmation. Default folder is .conan_manifests, but can be changed. - --verify [VERIFY], -v [VERIFY] - Verify dependencies manifests against stored ones - --no-imports Install specified packages but avoid running imports - -r REMOTE, --remote REMOTE - look in the specified remote server - --options OPTIONS, -o OPTIONS - Options to build the package, overwriting the defaults. e.g., -o with_qt=true - --settings SETTINGS, -s SETTINGS - Settings to build the package, overwriting the defaults. e.g., -s compiler=gcc - --env ENV, -e ENV Environment variables that will be set during the package build, - e.g. -e CXX=/usr/bin/clang++ - --build [BUILD [BUILD ...]], -b [BUILD [BUILD ...]] - Optional, use it to choose if you want to build from sources: - - --build Build all from sources, do not use binary packages. - --build=never Never build: use binary packages or fail - if a binary package is not found (default). - --build=missing Build from code if a binary package is not found. - --build=outdated Build from code if the binary is not built with the current - recipe or when missing binary package. - --build=[pattern] Always build these packages from source, but never build - the others. Allows multiple --build parameters. - - - - -**Examples** - -- Install a package requirement from a ``conanfile.txt``, saved in your current directory with one option and setting (other settings will be defaulted as defined in ``/.conan/conan.conf``): - -.. code-block:: bash - - $ conan install . -o use_debug_mode=on -s compiler=clang - - -.. note:: - - You have to take into account that **settings** are cached as defaults in the **conaninfo.txt** file, - so you don't have to type them again and again in the **conan install** or **conan test** - commands. - - However, the default **options** are defined in your **conanfile**. - If you want to change the default options across all your **conan install** commands, change - them in the **conanfile**. When you change the **options** on the command line, they are only changed - for one shot. Next time, **conan install** will take the **conanfile** options as default values, if you - don't specify them again in the command line. - - -- Install the **OpenCV/2.4.10@lasote/testing** reference with its default options and default settings from ``/.conan/conan.conf``: - -.. code-block:: bash - - $ conan install opencv/2.4.10@lasote/testing - - -- Install the **OpenCV/2.4.10@lasote/testing** reference updating the recipe and the binary package if new upstream versions are available: - -.. code-block:: bash - - $ conan install opencv/2.4.10@lasote/testing --update - - -.. _buildoptions: - - -build options -+++++++++++++ - -Both the conan **install** and **test** commands have options to specify whether conan should -try to build things or not: - -* :command:`--build=never` This is the default option. It is not necessary to write it explicitly. Conan will - not try to build packages when the requested configuration does not match, in which case it will - throw an error. -* :command:`--build=missing` Conan will try to build from source, all packages of which the requested configuration - was not found on any of the active remotes. -* :command:`--build=outdated` Conan will try to build from code if the binary is not built with the current recipe or when missing binary package -* :command:`--build=[pattern]` Conan will force the build of the packages, the name of which matches the given **pattern**. - Several patterns can be specified, chaining multiple options, e.g. :command:`--build=pattern1 --build=pattern2` -* :command:`--build` Always build everything from source. Produces a clean re-build of all packages - and transitively dependent packages - - -env variables -+++++++++++++ - -With the **-e** parameters you can define: - - - Global environment variables (``-e SOME_VAR="SOME_VALUE"``). These variables will be defined before the `build` step in all the packages and will be cleaned after the `build` execution. - - Specific package environment variables (``-e zlib:SOME_VAR="SOME_VALUE"``). These variables will be defined only in the specified packages (e.g. zlib). - -You can specify this variables not only for your direct ``requires`` but for any package in the dependency graph. - -If you want to define an environment variable but you want to append the variables declared in your -requirements you can use the [] syntax: - -.. code-block:: bash - - conan install -e PYTHONPATH=[/other/path] - -This way the first entry in the PYTHONPATH variable will be `/other/path` but the PYTHONPATH values declared in the requirements -of the project will be appended at the end using the system path separator. - - -settings -++++++++ - -With the **-s** parameters you can define: - - - Global settings (-s compiler="Visual Studio"). Will apply to all the requires. - - Specific package settings (-s zlib:compiler="MinGW"). Those settings will be applied only to the specified packages. - -You can specify custom settings not only for your direct ``requires`` but for any package in the dependency graph. - - -options -+++++++ - -With the **-o** parameters you can only define specific package options (-o zlib:shared=True). - - -.. note:: - - You can use :ref:`profiles ` files to create predefined sets of **settings**, **options**, **environment variables** and **scopes** - - -conan search ------------- - -.. code-block:: bash - - $ conan search [-r REMOTE] [pattern] - -Search both package recipes and package binaries in the local cache or in a remote server. -If you provide a pattern, then it will search for existing package recipes matching that pattern. - -You can search in a remote or in the local cache, if nothing is specified, the local conan cache is -assumed. - -.. code-block:: bash - - positional arguments: - pattern Pattern name, e.g. openssl/* or package recipe - reference if "-q" is used. e.g. - MyPackage/1.2@user/channel - - optional arguments: - -h, --help show this help message and exit - --case-sensitive Make a case-sensitive search - -r REMOTE, --remote REMOTE - Remote origin - -q QUERY, --query QUERY - Packages query: "os=Windows AND (arch=x86 OR - compiler=gcc)". The "pattern" parameter has to be a - package recipe reference: MyPackage/1.2@user/channel - -**Examples** - - -.. code-block:: bash - - $ conan search OpenCV/* - $ conan search OpenCV/* -r=conan.io - - -If you use instead the full package recipe reference, you can explore the binaries existing for -that recipe, also in a remote or in the local conan cache: - -.. code-block:: bash - - $ conan search Boost/1.60.0@lasote/stable - -A query syntax is allowed to look for specific binaries, you can use ``AND`` and ``OR`` operators and parenthesis, with settings and also options. - -.. code-block:: bash - - $ conan search Boost/1.60.0@lasote/stable -q arch=x86_64 - $ conan search Boost/1.60.0@lasote/stable -q "(arch=x86_64 OR arch=ARM) AND (build_type=Release OR os=Windows)" - - -If you specify a query filter for a setting and the package recipe is not restricted by this setting, will find all packages: - -.. code-block:: python - - class MyRecipe(ConanFile): - settings="arch" - - -.. code-block:: bash - - $ conan search MyRecipe/1.0@lasote/stable -q os=Windows - - -The query above will find all the ``MyRecipe`` binary packages, because the recipe doesn't declare "os" as a setting. - - -conan info ----------- - -.. code-block:: bash - - $ usage: conan info [-h] [--file FILE] [--only [ONLY]] - [--build_order BUILD_ORDER] [--update] [--scope SCOPE] - [--profile PROFILE] [-r REMOTE] [--options OPTIONS] - [--settings SETTINGS] [--env ENV] - [--build [BUILD [BUILD ...]]] - [reference] - -Prints information about a package recipe's dependency graph. -You can use it for your current project (just point to the path of your conanfile if you want), or for any -existing package in your local cache. - - -The ``--update`` option will check if there is any new recipe/package available in remotes. Use ``conan install -u`` -to update them. - - -.. code-block:: bash - - positional arguments: - reference reference name or path to conanfile file, e.g., - MyPackage/1.2@user/channel or ./my_project/ - - optional arguments: - --file FILE, -f FILE specify conanfile filename - --only [ONLY], -n [ONLY] - show fields only - --build_order BUILD_ORDER, -bo BUILD_ORDER - given a modified reference, return an ordered list to - build (CI) - --update, -u check updates exist from upstream remotes - --scope SCOPE, -sc SCOPE - Use the specified scope in the install command - --profile PROFILE, -pr PROFILE - Apply the specified profile to the install command - -r REMOTE, --remote REMOTE - look in the specified remote server - --options OPTIONS, -o OPTIONS - Options to build the package, overwriting the - defaults. e.g., -o with_qt=true - --settings SETTINGS, -s SETTINGS - Settings to build the package, overwriting the - defaults. e.g., -s compiler=gcc - --env ENV, -e ENV Environment variables that will be set during the - package build, -e CXX=/usr/bin/clang++ - --build [BUILD [BUILD ...]], -b [BUILD [BUILD ...]] - given a build policy (same install command "build" - parameter), return an ordered list of packages that - would be built from sources in install command - (simulation) - - -**Examples**: - -.. code-block:: bash - - $ conan info - $ conan info myproject_path - $ conan info Hello/1.0@user/channel - -The output will look like: - -.. code-block:: bash - - Dependency/0.1@user/channel - URL: http://... - License: MIT - Updates: Version not checked - Required by: - Hello/1.0@user/channel - - Hello/1.0@user/channel - URL: http://... - License: MIT - Updates: Version not checked - Required by: - Project - Requires: - Hello0/0.1@user/channel - - -It is possible to use the ``conan info`` command to extract useful information for Continuous -Integration systems. More precisely, it has the ``--build_order, -bo`` option, that will produce -a machine-readable output with an ordered list of package references, in the order they should be -built. E.g., lets assume that we have a project that depends on Boost and Poco, which in turn -depends on OpenSSL and ZLib transitively. So we can query our project with a reference that has -changed (most likely due to a git push on that package): - -.. code-block:: bash - - $ conan info -bo zlib/1.2.8@lasote/stable - [zlib/1.2.8@lasote/stable], [OpenSSL/1.0.2g@lasote/stable], [Boost/1.60.0@lasote/stable, Poco/1.7.2@lasote/stable] - -Note the result is a list of lists. When there is more than one element in one of the lists, it means -that they are decoupled projects and they can be built in parallel by the CI system. - -Also you can get a list of nodes that would be built (simulation) in an install command specifying a build policy with the ``--build`` parameter: - -e.g., If I try to install ``Boost/1.60.0@lasote/stable`` recipe with ``--build missing`` build policy and ``arch=x86``, which libraries will be build? - -.. code-block:: bash - - $ conan info Boost/1.60.0@lasote/stable --build missing -s arch=x86 - bzip2/1.0.6@lasote/stable, zlib/1.2.8@lasote/stable, Boost/1.60.0@lasote/stable - - - - -conan remote ------------- - -.. code-block:: bash - - $ conan remote [-h] {list,add,remove,update,list_ref,add_ref,remove_ref,update_ref} - - -Handles the remote list and the package recipes associated to a remote. - - -.. code-block:: bash - - positional arguments: - {list,add,remove,update,list_ref,add_ref,remove_ref,update_ref} - sub-command help - list list current remotes - add add a remote - remove remove a remote - update update the remote url - list_ref list the package recipes and its associated remotes - add_ref associate a recipe's reference to a remote - remove_ref dissociate a recipe's reference and its remote - update_ref update the remote associated with a package recipe - - optional arguments: - -h, --help show this help message and exit - - -**Examples** - -- List remotes: - -.. code-block:: bash - - $ conan remote list - - conan.io: https://server.conan.io [Verify SSL: True] - local: http://localhost:9300 [Verify SSL: True] - - - -- Add a new remote: - -.. code-block:: bash - - $ conan remote add remote_name remote_url [verify_ssl] - - -Verify SSL option can be True or False (default True). Conan client will verify the SSL certificates. - - -- Remove a remote: - -.. code-block:: bash - - $ conan remote remove remote_name - - -- Update a remote: - -.. code-block:: bash - - $ conan remote update remote_name new_url [verify_ssl] - - -- List the package recipes and its associated remotes: - -.. code-block:: bash - - $ conan remote list_ref - - bzip2/1.0.6@lasote/stable: conan.io - Boost/1.60.0@lasote/stable: conan.io - zlib/1.2.8@lasote/stable: conan.io - - -- Associate a recipe's reference to a remote: - - -.. code-block:: bash - - $ conan remote add_ref package_recipe_ref remote_name - - -- Update the remote associated with a package recipe: - -.. code-block:: bash - - $ conan remote update_ref package_recipe_ref new_remote_name - - - - -conan profile -------------- - -.. code-block:: bash - - $ conan profile [-h] {list,show} ... - - -List all the profiles that exist in the ``.conan/profiles`` folder, or show details for a given profile. -The ``list`` subcommand will always use the default user ``.conan/profiles`` folder. But the -``show`` subcommand is able to resolve absolute and relative paths, as well as to map names to -``.conan/profiles`` folder, in the same way as the ``--profile`` install argument. - - -.. code-block:: bash - - positional arguments: - {list,show} sub-command help - list list current profiles - show show the values defined for a profile. Can be a path (relative - or absolute) to a profile file in any location. - - -**Examples** - -- List the profiles: - -.. code-block:: bash - - $ conan profile list - > myprofile1 - > myprofile2 - -- Print profile contents: - -.. code-block:: bash - - $ conan profile show myprofile1 - Profile myprofile1 - [settings] - ... - -- Print profile contents (in the standard directory ``.conan/profiles``): - -.. code-block:: bash - - $ conan profile show myprofile1 - Profile myprofile1 - [settings] - ... - -- Print profile contents (in a custom directory): - -.. code-block:: bash - - $ conan profile show /path/to/myprofile1 - Profile myprofile1 - [settings] - ... - - - -conan upload ------------- - -.. code-block:: bash - - $ conan upload [-h] [--package PACKAGE] [--remote REMOTE] [--all] - [--force] [--confirm] [--retry RETRY] - [--retry_wait RETRY_WAIT] - pattern - -Uploads recipes and binary packages from your local cache to a remote server. - -If you use the ``--force`` variable, it won't check the package date. It will override the remote with the local package. - -If you use a pattern instead of a conan recipe reference you can use the ``-c`` or ``--confirm`` option to upload all the matching recipes. - -If you use the ``--retry`` option you can specify how many times should conan try to upload the packages in case of failure. The default is 2. -With ``--retry_wait`` you can specify the seconds to wait between upload attempts. - -If not remote is specified, the first configured remote (by default conan.io, use -``conan remote list`` to list the remotes) will be used. - - -.. code-block:: bash - - positional arguments: - pattern Pattern or package recipe reference, e.g., - "openssl/*", "MyPackage/1.2@user/channel" - - optional arguments: - -h, --help show this help message and exit - --package PACKAGE, -p PACKAGE - package ID to upload - --remote REMOTE, -r REMOTE - upload to this specific remote - --all Upload both package recipe and packages - --force Do not check conan recipe date, override remote with - local - --confirm, -c If pattern is given upload all matching recipes - without confirmation - --retry RETRY In case of fail it will retry the upload again N times - --retry_wait RETRY_WAIT - Waits specified seconds before retry again - - -**Examples**: - -Uploads a package recipe (conanfile.py and the exported files): - -.. code-block:: bash - - $ conan upload OpenCV/1.4.0@lasote/stable - -Uploads a package recipe and all the generated binary packages to a specified remote: - -.. code-block:: bash - - $ conan upload OpenCV/1.4.0@lasote/stable --all -r my_remote - - -Uploads all recipes and binary packages from our local cache to ``my_remote`` without confirmation: - -.. code-block:: bash - - $ conan upload "*" --all -r my_remote -c - -Upload all local packages and recipes beginning with "Op" retrying 3 times and waiting 10 seconds between upload attempts: - -.. code-block:: bash - - $ conan upload "Op*" --all -r my_remote -c --retry 3 --retry_wait 10 - - -conan remove ------------- - -.. code-block:: bash - - $ conan remove [-h] [-p [PACKAGES [PACKAGES ...]]] - [-b [BUILDS [BUILDS ...]]] [-s] [-f] [-r REMOTE] - [-q QUERY] - pattern - - -Remove any package recipe or binary matching a pattern. It can also be used to remove -temporary source or build folders in the local conan cache. - -If no remote is specified, the removal will be done by default in the local conan cache. - - -.. code-block:: bash - - positional arguments: - pattern Pattern name, e.g., openssl/* - - optional arguments: - -h, --help show this help message and exit - -p [PACKAGES [PACKAGES ...]], --packages [PACKAGES [PACKAGES ...]] - By default, remove all the packages or select one, - specifying the package ID - -b [BUILDS [BUILDS ...]], --builds [BUILDS [BUILDS ...]] - By default, remove all the build folders or select - one, specifying the package ID - -s, --src Remove source folders - -f, --force Remove without requesting a confirmation - -r REMOTE, --remote REMOTE - Will remove from the specified remote - -q QUERY, --query QUERY - Packages query: "os=Windows AND (arch=x86 OR - compiler=gcc)". The "pattern" parameter has to be a - package recipe reference: MyPackage/1.2@user/channel - - -The ``-q`` parameter can't be used along with ``-p`` nor ``-b`` parameters. - -**Examples**: - -- Remove from the local conan cache the binary packages (the package recipes will not be removed) - from all the recipes matching ``OpenSSL/*`` pattern: - - -.. code-block:: bash - - $ conan remove OpenSSL/* --packages - - -- Remove the temporary build folders from all the recipes matching ``OpenSSL/*`` pattern without requesting confirmation: - -.. code-block:: bash - - $ conan remove OpenSSL/* --builds --force - - -- Remove the recipe and the binary packages from a specific remote: - -.. code-block:: bash - - $ conan remove OpenSSL/1.0.2@lasote/stable -r myremote - - -- Remove only Windows OpenSSL packages from local cache: - -.. code-block:: bash - - $ conan remove OpenSSL/1.0.2@lasote/stable -q "os=Windows" - - - -conan user ----------- - -.. code-block:: bash - - $ conan user [-h] [-p PASSWORD] [--remote REMOTE] [-c] [name] - -Update your cached user name (and auth token) to avoid it being requested later, e.g. while you're uploading a package. -You can have more than one user (one per remote). Changing the user, or introducing the password is only necessary to upload -packages to a remote. - -.. code-block:: bash - - positional arguments: - name Username you want to use. If no name is provided it - will show the current user. - - optional arguments: - -h, --help show this help message and exit - -p PASSWORD, --password PASSWORD - User password. Use double quotes if password with - spacing, and escape quotes if existing - --remote REMOTE, -r REMOTE - look in the specified remote server - -c, --clean Remove user and tokens for all remotes - - - -**Examples**: - -- List my user for each remote: - -.. code-block:: bash - - $ conan user - - -- Change **conan.io** remote user to **foo**: - -.. code-block:: bash - - $ conan user foo -r conan.io - -- Change **conan.io** remote user to **foo**, authenticating against the remote and storing the - user and authentication token locally, so a later upload won't require entering credentials: - -.. code-block:: bash - - $ conan user foo -r conan.io -p mypassword - -- Clean all local users and tokens - -.. code-block:: bash - - $ conan user --clean - - -.. note:: - - The password is not stored in the client computer at any moment. Conan uses `JWT `: conan - gets a token (expirable by the server) checking the password against the remote credentials. - If the password is correct, an authentication token will be obtained, and that token is the - information cached locally. For any subsequent interaction with the remotes, the conan client will only use that JWT token. - - -conan copy ----------- - -.. code-block:: bash - - $ conan copy package_recipe_ref otheruser/otherchannel - - -Copy conan recipes and packages to another user/channel. Useful to promote packages (e.g. from "beta" to "stable"). -Also for moving packages from one user to another. - - -.. code-block:: bash - - positional arguments: - reference package recipe reference, e.g. - MyPackage/1.2@user/channel - user_channel Destination user/channel, e.g. lasote/testing - - optional arguments: - -h, --help show this help message and exit - --package PACKAGE, -p PACKAGE - copy specified package ID - --all Copy all packages from the specified package recipe - --force Override destination packages and the package recipe - - -**Examples** - -- Promote a package to **stable** from **beta**: - -.. code-block:: bash - - $ conan copy OpenSSL/1.0.2i@lasote/beta lasote/stable - - -- Change a package's username: - -.. code-block:: bash - - $ conan copy OpenSSL/1.0.2i@lasote/beta foo/beta - - -.. _conan_new: - -conan new ---------- - -.. code-block:: bash - - $ conan new [-h] [-t] [-i] [-c] name - - -Creates a new package recipe template with a ``conanfile.py`` and optionally, ``test_package`` -package testing files. - -.. code-block:: bash - - positional arguments: - name Package name, e.g.: Poco/1.7.3@user/testing - - optional arguments: - -h, --help show this help message and exit - -t, --test Create test_package skeleton to test package - -i, --header Create a headers only package template - -c, --pure_c Create a C language package only package, - deleting "self.settings.compiler.libcxx" setting in the configure method - - -**Examples**: - - -- Create a new ``conanfile.py`` for a new package **mypackage/1.0@myuser/stable** - -.. code-block:: bash - - $ conan new mypackage/1.0@myuser/stable - - -- Create also a ``test_package`` folder skeleton: - -.. code-block:: bash - - $ conan new mypackage/1.0@myuser/stable -t - - - - -conan test_package ------------------- - -.. code-block:: bash - - $ conan test_package [-h] [-ne] [-f FOLDER] [--scope SCOPE] - [--keep-source] [--update] [--profile PROFILE] - [-r REMOTE] [--options OPTIONS] - [--settings SETTINGS] [--env ENV] - [--build [BUILD [BUILD ...]]] - [path] - - - -The ``test_package`` (previously named **test**) command looks for a **test_package subfolder** in the current directory, and builds the -project that is in it. It will typically be a project with a single requirement, pointing to -the ``conanfile.py`` being developed in the current directory. - -This was mainly intended to do a test of the package, not to run unit or integrations tests on the package -being created. Those tests could be launched if desired in the ``build()`` method. -But it can be used for that purpose if desired, there are no real technical constraints. - -The command line arguments are exactly the same as the settings, options, and build parameters -for the ``install`` command, with one small difference: - -In conan test, by default, the ``--build=CurrentPackage`` pattern is automatically appended for the -current tested package. You can always manually specify other build options, like ``--build=never``, -if you just want to check that the current existing package works for the test subproject, without -re-building it. - -You can use the ``conan new`` command with the ``-t`` option to generate a ``test_package`` skeleton. - - -.. code-block:: bash - - positional arguments: - path path to conanfile file, e.g. /my_project/ - - optional arguments: - -ne, --not-export Do not export the conanfile before test execution - -f FOLDER, --folder FOLDER - alternative test folder name - --scope SCOPE, -sc SCOPE - Use the specified scope in the install command - --keep-source, -k Optional. Do not remove the source folder in local cache. - Use for testing purposes only - --update, -u update with new upstream packages, overwriting the local cache if needed. - --profile PROFILE, -pr PROFILE - Apply the specified profile to the install command - -r REMOTE, --remote REMOTE - look in the specified remote server - --options OPTIONS, -o OPTIONS - Options to build the package, overwriting the defaults. e.g., -o with_qt=true - --settings SETTINGS, -s SETTINGS - Settings to build the package, overwriting the defaults. e.g., -s compiler=gcc - --env ENV, -e ENV Environment variables to set during the package build, - e.g. -e CXX=/usr/bin/clang++ - --build [BUILD [BUILD ...]], -b [BUILD [BUILD ...]] - Optional, use it to choose if you want to build from sources: - - --build Build all from sources, do not use binary packages. - --build=never Default option. Never build, use binary packages - or fail if a binary package is not found. - --build=missing Build from code if a binary package is not found. - --build=outdated Build from code if the binary is not built with the - current recipe or when missing binary package. - --build=[pattern] Build always these packages from source, but never build - the others. Allows multiple --build parameters. - - - -If you want to use a different folder name than **test_package**, just use it and pass it to the ``-f folder`` -command line option - -.. code-block:: bash - - $ conan test_package --f my_test_folder - - -This command will run the equivalent to ``conan export /`` where ``user`` and ``channel`` -will be deduced from the values of the requirement in the ``conanfile.py`` inside the test subfolder. -This is very convenient, as if you are running a package test it is extremely likely that you have -just edited the package recipe. If the package recipe is locally modified, it has to be exported again, -otherwise, the package will be tested with the old recipe. If you want to inhibit this ``export``, -you can use the ``-ne, --no-export`` parameter. - - -conan source ------------- - -.. code-block:: bash - - $ conan source [-h] [-f] [reference] - - -The ``source`` command executes a conanfile.py ``source()`` method, retrieving source code as -defined in the method, both locally, in user space or for a package in the local cache. - - -.. code-block:: bash - - positional arguments: - reference package recipe reference. e.g., MyPackage/1.2@user/channel or - ./my_project/ - - optional arguments: - -h, --help show this help message and exit - -f, --force In the case of local cache, force the removal of the source - folder, then the execution and retrieval of the source code. - Otherwise, if the code has already been retrieved, it will do - nothing. - - -The ``conan source`` and the ``source()`` method might use dependencies information, either from -``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if -using the ``txt`` generator in the ``conanbuildinfo.txt``. -So, if the ``conan source`` command is to be used, the recommended way to run install would be: - -.. code-block:: bash - - $ conan install .. -g txt - -or adding ``txt`` generator to the consuming conanfile ``generators`` section - - -**Examples**: - -- Call a local recipe's source method: In user space, the command will execute a local conanfile.py - ``source()`` method, in the current directory. - -.. code-block:: bash - - $ conan source ../mysource_folder - - -- Call a cached recipe's source method: In the conan local cache, it will execute the recipe ``source()`` , - in the corresponding ``source`` folder, as defined by the local cache layout. - This command is useful for retrieving such source code before launching multiple concurrent package builds, - that could otherwise collide in the source code retrieval process. - -.. code-block:: bash - - $ conan source Pkg/0.2@user/channel - - - -conan build ------------ - - -.. code-block:: bash - - $ conan build conan build [-h] [--file FILE] [path] - -Utility command to run your current project **conanfile.py** ``build()`` method. It doesn't -work for **conanfile.txt**. It is convenient for automatic translation of conan settings and options, -for example to CMake syntax, as it can be done by the CMake helper. It is also a good starting point -if you would like to create a package from your current project. - - - -.. code-block:: bash - - positional arguments: - path path to conanfile.py, e.g., conan build . - - optional arguments: - -h, --help show this help message and exit - --file FILE, -f FILE specify conanfile filename - - - -The ``conan build`` and the ``build()`` method might use dependencies information, either from -``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if -using the ``txt`` generator in the ``conanbuildinfo.txt``. -So, if the ``conan build`` command is to be used, the recommended way to run install would be: - -.. code-block:: bash - - $ conan install .. -g txt - -or adding ``txt`` generator to the consuming conanfile ``generators`` section - - -conan package -------------- - -.. code-block:: bash - - $ conan package [-h] reference [package] - - -Calls your conanfile.py ``package()`` method for a specific package recipe. -Intended for package creators, for regenerating a package without recompiling -the source, i.e. for troubleshooting, and fixing the ``package()`` method, not -normal operation. - -It requires that the package has been built locally, it won't -re-package otherwise. When used in a user space project, it -will execute from the build folder specified as parameter, and the current -directory. This is useful while creating package recipes or just for -extracting artifacts from the current project, without even being a package - -This command also works locally, in the user space, and it will copy artifacts from the provided -folder to the current one. - -.. code-block:: bash - - positional arguments: - reference package recipe reference e.g. MyPkg/0.1@user/channel, or local - path to the build folder (relative or absolute) - package Package ID to regenerate. e.g., - 9cf83afd07b678d38a9c1645f605875400847ff3 This optional parameter - is only used for the local conan cache. If not specified, ALL binaries - for this recipe are re-packaged - -The ``conan package`` and the ``package()`` method might use dependencies information, either from -``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if -using the ``txt`` generator in the ``conanbuildinfo.txt``. -So, if the ``conan package`` command is to be used, the recommended way to run install would be: - -.. code-block:: bash - - $ conan install .. -g txt - -or adding ``txt`` generator to the consuming conanfile ``generators`` section - - -**Examples** - - -- Copy artifacts from the provided ``build`` folder to the current one: - -.. code-block:: bash - - $ conan package ../build - - -- Copy the artifacts from the build directory to package directory in the local cache: - - -.. code-block:: bash - - $ conan package MyPackage/1.2@user/channel 9cf83afd07b678da9c1645f605875400847ff3 - - -.. note:: - - Conan package command won't create a new package, use ``install`` or ``test_package`` instead for - creating packages in the conan local cache, or ``build`` for conanfile.py in user space. - - - -conan imports -------------- - -.. code-block:: bash - - $ conan imports [-h] [--file FILE] [-d DEST] [-u] [reference] - - - -Execute the ``imports`` stage of a conanfile.txt or a conanfile.py. It requires -to have been previously installed it and have a ``conanbuildinfo.txt`` generated file. - -The ``imports`` functionality needs a ``conanbuildinfo.txt`` file, so it has -to be generated with a previous ``conan install`` either specifying it in the conanfile, or as -a command line parameter. It will generate a manifest file called ``conan_imports_manifests.txt`` -with the files that have been copied from conan local cache to user space. - - -.. code-block:: bash - - positional arguments: - reference Specify the location of the folder containing the - conanfile. By default it will be the current directory. - It can also use a full reference e.g. - MyPackage/1.2@user/channel and the recipe - 'imports()' for that package in the local conan cache - will be used - - optional arguments: - -h, --help show this help message and exit - --file FILE, -f FILE Use another filename, e.g.: conan imports - -f=conanfile2.py - -d DEST, --dest DEST Directory to copy the artifacts to. By default it will - be the current directory - -u, --undo Undo imports. Remove imported files - -The ``conan imports`` and the ``imports()`` method might use dependencies information, either from -``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if -using the ``txt`` generator in the ``conanbuildinfo.txt``. -So, if the ``conan imports`` command is to be used, the recommended way to run install would be: - -.. code-block:: bash - - $ conan install .. -g txt - -or adding ``txt`` generator to the consuming conanfile ``generators`` section - - - -**Examples** - -- Execute the ``imports()`` method for a package in the local cache: - - -.. code-block:: bash - - $ conan imports MyPackage/1.2@user/channel - - -- Import files from a current conanfile in current directory: - -.. code-block:: bash - - $ conan install --no-imports -g txt # Creates the conanbuildinfo.txt - $ conan imports - - -- Remove the copied files (undo the import): - - -.. code-block:: bash - - $ conan imports --undo - - -conan config ------------- - -.. code-block:: bash - - $ conan config [-h] {rm,set,get} ... - - -Manages conan.conf information. - -.. code-block:: bash - - positional arguments: - {rm,set,get} sub-command help - rm rm an existing config element - set set/add value - get get the value of existing element - - -**Examples** - -- Change the logging level to 10: - -.. code-block:: bash - - $ conan config set log.level=10 - -- Get the logging level: - -.. code-block:: bash - - $ conan config get log.level - $> 10 - - +Conan command reference: + + +.. toctree:: + :maxdepth: 2 + + commands/export.rst + commands/install.rst + commands/search.rst + commands/info.rst + commands/remote.rst + commands/profile.rst + commands/upload.rst + commands/remove.rst + commands/user.rst + commands/copy.rst + commands/new.rst + commands/test_package.rst + commands/source.rst + commands/build.rst + commands/package.rst + commands/imports.rst + commands/config.rst diff --git a/reference/commands/build.rst b/reference/commands/build.rst new file mode 100644 index 000000000000..b0bdbe7a881e --- /dev/null +++ b/reference/commands/build.rst @@ -0,0 +1,38 @@ + +conan build +=========== + + +.. code-block:: bash + + $ conan build conan build [-h] [--file FILE] [path] + +Utility command to run your current project **conanfile.py** ``build()`` method. It doesn't +work for **conanfile.txt**. It is convenient for automatic translation of conan settings and options, +for example to CMake syntax, as it can be done by the CMake helper. It is also a good starting point +if you would like to create a package from your current project. + + + +.. code-block:: bash + + positional arguments: + path path to conanfile.py, e.g., conan build . + + optional arguments: + -h, --help show this help message and exit + --file FILE, -f FILE specify conanfile filename + + + +The ``conan build`` and the ``build()`` method might use dependencies information, either from +``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if +using the ``txt`` generator in the ``conanbuildinfo.txt``. +So, if the ``conan build`` command is to be used, the recommended way to run install would be: + +.. code-block:: bash + + $ conan install .. -g txt + +or adding ``txt`` generator to the consuming conanfile ``generators`` section + diff --git a/reference/commands/config.rst b/reference/commands/config.rst new file mode 100644 index 000000000000..e5c3553190d2 --- /dev/null +++ b/reference/commands/config.rst @@ -0,0 +1,37 @@ + +conan config +============ + + +.. code-block:: bash + + $ conan config [-h] {rm,set,get} ... + + +Manages conan.conf information. + +.. code-block:: bash + + positional arguments: + {rm,set,get} sub-command help + rm rm an existing config element + set set/add value + get get the value of existing element + + +**Examples** + +- Change the logging level to 10: + +.. code-block:: bash + + $ conan config set log.level=10 + +- Get the logging level: + +.. code-block:: bash + + $ conan config get log.level + $> 10 + + diff --git a/reference/commands/copy.rst b/reference/commands/copy.rst new file mode 100644 index 000000000000..a61c070100e3 --- /dev/null +++ b/reference/commands/copy.rst @@ -0,0 +1,43 @@ + +conan copy +========== + + +.. code-block:: bash + + $ conan copy package_recipe_ref otheruser/otherchannel + + +Copy conan recipes and packages to another user/channel. Useful to promote packages (e.g. from "beta" to "stable"). +Also for moving packages from one user to another. + + +.. code-block:: bash + + positional arguments: + reference package recipe reference, e.g. + MyPackage/1.2@user/channel + user_channel Destination user/channel, e.g. lasote/testing + + optional arguments: + -h, --help show this help message and exit + --package PACKAGE, -p PACKAGE + copy specified package ID + --all Copy all packages from the specified package recipe + --force Override destination packages and the package recipe + + +**Examples** + +- Promote a package to **stable** from **beta**: + +.. code-block:: bash + + $ conan copy OpenSSL/1.0.2i@lasote/beta lasote/stable + + +- Change a package's username: + +.. code-block:: bash + + $ conan copy OpenSSL/1.0.2i@lasote/beta foo/beta diff --git a/reference/commands/export.rst b/reference/commands/export.rst new file mode 100644 index 000000000000..e4cc6486a500 --- /dev/null +++ b/reference/commands/export.rst @@ -0,0 +1,53 @@ + +conan export +============ + + +.. code-block:: bash + + $ conan export [-h] [--path PATH] [--keep-source] user + +Copies the package recipe (conanfile.py and associated files) to your local cache. +From the local cache it can be shared and reused in other projects. +Also, from the local cache, it can be uploaded to any remote with the "upload" command. + + +.. code-block:: bash + + + positional arguments: + user user_name[/channel]. By default, channel is "testing", + e.g., phil or phil/stable + + optional arguments: + --path PATH, -p PATH Optional. Folder with a conanfile.py. Default current + directory. + --keep-source, -k Optional. Do not remove the source folder in the local + cache. Use for testing purposes only + + + + +**Examples** + + +- Export a recipe from the current directory, under the ``myuser/testing`` user and channel: + +.. code-block:: bash + + $ conan export myuser + + +- Export a recipe from any folder directory, under the ``myuser/stable`` user and channel: + +.. code-block:: bash + + $ conan export ./folder_name myuser/stable + + +- Export a recipe without removing the source folder in the local cache: + +.. code-block:: bash + + $ conan export fenix/stable -k + diff --git a/reference/commands/imports.rst b/reference/commands/imports.rst new file mode 100644 index 000000000000..8b340db29d61 --- /dev/null +++ b/reference/commands/imports.rst @@ -0,0 +1,75 @@ + + +conan imports +============= + +.. code-block:: bash + + $ conan imports [-h] [--file FILE] [-d DEST] [-u] [reference] + + + +Execute the ``imports`` stage of a conanfile.txt or a conanfile.py. It requires +to have been previously installed it and have a ``conanbuildinfo.txt`` generated file. + +The ``imports`` functionality needs a ``conanbuildinfo.txt`` file, so it has +to be generated with a previous ``conan install`` either specifying it in the conanfile, or as +a command line parameter. It will generate a manifest file called ``conan_imports_manifests.txt`` +with the files that have been copied from conan local cache to user space. + + +.. code-block:: bash + + positional arguments: + reference Specify the location of the folder containing the + conanfile. By default it will be the current directory. + It can also use a full reference e.g. + MyPackage/1.2@user/channel and the recipe + 'imports()' for that package in the local conan cache + will be used + + optional arguments: + -h, --help show this help message and exit + --file FILE, -f FILE Use another filename, e.g.: conan imports + -f=conanfile2.py + -d DEST, --dest DEST Directory to copy the artifacts to. By default it will + be the current directory + -u, --undo Undo imports. Remove imported files + +The ``conan imports`` and the ``imports()`` method might use dependencies information, either from +``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if +using the ``txt`` generator in the ``conanbuildinfo.txt``. +So, if the ``conan imports`` command is to be used, the recommended way to run install would be: + +.. code-block:: bash + + $ conan install .. -g txt + +or adding ``txt`` generator to the consuming conanfile ``generators`` section + + + +**Examples** + +- Execute the ``imports()`` method for a package in the local cache: + + +.. code-block:: bash + + $ conan imports MyPackage/1.2@user/channel + + +- Import files from a current conanfile in current directory: + +.. code-block:: bash + + $ conan install --no-imports -g txt # Creates the conanbuildinfo.txt + $ conan imports + + +- Remove the copied files (undo the import): + + +.. code-block:: bash + + $ conan imports --undo diff --git a/reference/commands/info.rst b/reference/commands/info.rst new file mode 100644 index 000000000000..d710cc9f50e9 --- /dev/null +++ b/reference/commands/info.rst @@ -0,0 +1,111 @@ + + +conan info +========== + +.. code-block:: bash + + $ usage: conan info [-h] [--file FILE] [--only [ONLY]] + [--build_order BUILD_ORDER] [--update] [--scope SCOPE] + [--profile PROFILE] [-r REMOTE] [--options OPTIONS] + [--settings SETTINGS] [--env ENV] + [--build [BUILD [BUILD ...]]] + [reference] + +Prints information about a package recipe's dependency graph. +You can use it for your current project (just point to the path of your conanfile if you want), or for any +existing package in your local cache. + + +The ``--update`` option will check if there is any new recipe/package available in remotes. Use ``conan install -u`` +to update them. + + +.. code-block:: bash + + positional arguments: + reference reference name or path to conanfile file, e.g., + MyPackage/1.2@user/channel or ./my_project/ + + optional arguments: + --file FILE, -f FILE specify conanfile filename + --only [ONLY], -n [ONLY] + show fields only + --build_order BUILD_ORDER, -bo BUILD_ORDER + given a modified reference, return an ordered list to + build (CI) + --update, -u check updates exist from upstream remotes + --scope SCOPE, -sc SCOPE + Use the specified scope in the install command + --profile PROFILE, -pr PROFILE + Apply the specified profile to the install command + -r REMOTE, --remote REMOTE + look in the specified remote server + --options OPTIONS, -o OPTIONS + Options to build the package, overwriting the + defaults. e.g., -o with_qt=true + --settings SETTINGS, -s SETTINGS + Settings to build the package, overwriting the + defaults. e.g., -s compiler=gcc + --env ENV, -e ENV Environment variables that will be set during the + package build, -e CXX=/usr/bin/clang++ + --build [BUILD [BUILD ...]], -b [BUILD [BUILD ...]] + given a build policy (same install command "build" + parameter), return an ordered list of packages that + would be built from sources in install command + (simulation) + + +**Examples**: + +.. code-block:: bash + + $ conan info + $ conan info myproject_path + $ conan info Hello/1.0@user/channel + +The output will look like: + +.. code-block:: bash + + Dependency/0.1@user/channel + URL: http://... + License: MIT + Updates: Version not checked + Required by: + Hello/1.0@user/channel + + Hello/1.0@user/channel + URL: http://... + License: MIT + Updates: Version not checked + Required by: + Project + Requires: + Hello0/0.1@user/channel + + +It is possible to use the ``conan info`` command to extract useful information for Continuous +Integration systems. More precisely, it has the ``--build_order, -bo`` option, that will produce +a machine-readable output with an ordered list of package references, in the order they should be +built. E.g., lets assume that we have a project that depends on Boost and Poco, which in turn +depends on OpenSSL and ZLib transitively. So we can query our project with a reference that has +changed (most likely due to a git push on that package): + +.. code-block:: bash + + $ conan info -bo zlib/1.2.8@lasote/stable + [zlib/1.2.8@lasote/stable], [OpenSSL/1.0.2g@lasote/stable], [Boost/1.60.0@lasote/stable, Poco/1.7.2@lasote/stable] + +Note the result is a list of lists. When there is more than one element in one of the lists, it means +that they are decoupled projects and they can be built in parallel by the CI system. + +Also you can get a list of nodes that would be built (simulation) in an install command specifying a build policy with the ``--build`` parameter: + +e.g., If I try to install ``Boost/1.60.0@lasote/stable`` recipe with ``--build missing`` build policy and ``arch=x86``, which libraries will be build? + +.. code-block:: bash + + $ conan info Boost/1.60.0@lasote/stable --build missing -s arch=x86 + bzip2/1.0.6@lasote/stable, zlib/1.2.8@lasote/stable, Boost/1.60.0@lasote/stable + diff --git a/reference/commands/install.rst b/reference/commands/install.rst new file mode 100644 index 000000000000..a72da38d47ec --- /dev/null +++ b/reference/commands/install.rst @@ -0,0 +1,176 @@ +.. _conan_install_command: + +conan install +============= + + +.. code-block:: bash + + $ conan install [-h] [--package PACKAGE] [--all] [--file FILE] [--update] + [--scope SCOPE] [--profile PROFILE] + [--generator GENERATOR] [--werror] + [--manifests [MANIFESTS]] + [--manifests-interactive [MANIFESTS_INTERACTIVE]] + [--verify [VERIFY]] [--no-imports] [-r REMOTE] + [--options OPTIONS] [--settings SETTINGS] [--env ENV] + [--build [BUILD [BUILD ...]]] + [reference] + + + +Installs the requirements specified in a ``conanfile.py`` or ``conanfile.txt``. +It can also be used to install a concrete recipe/package specified by the ``reference`` parameter. +If the recipe is not found in the local cache it will retrieve the recipe from a remote, looking +for it sequentially in the available configured remotes. +When the recipe has been downloaded it will try to download a binary package matching the specified settings, +only from the remote from which the recipe was retrieved. +If no binary package is found you can build the package from sources using the ``--build`` option. + + +.. code-block:: bash + + + positional arguments: + reference package recipe reference, e.g. MyPackage/1.2@user/channel or ./my_project/ + + optional arguments: + --package PACKAGE, -p PACKAGE + Force install specified package ID (ignore settings/options) + --all Install all packages from the specified package recipe + --file FILE, -f FILE specify conanfile filename + --update, -u update with new upstream packages, overwriting the local cache if needed. + --scope SCOPE, -sc SCOPE + Use the specified scope in the install command + --profile PROFILE, -pr PROFILE + Apply the specified profile to the install command + --generator GENERATOR, -g GENERATOR + Generators to use + --werror Error instead of warnings for graph inconsistencies + --manifests [MANIFESTS], -m [MANIFESTS] + Install dependencies manifests in folder for later verify. + Default folder is .conan_manifests, but can be changed. + --manifests-interactive [MANIFESTS_INTERACTIVE], -mi [MANIFESTS_INTERACTIVE] + Install dependencies manifests in folder for later verify, asking user for + confirmation. Default folder is .conan_manifests, but can be changed. + --verify [VERIFY], -v [VERIFY] + Verify dependencies manifests against stored ones + --no-imports Install specified packages but avoid running imports + -r REMOTE, --remote REMOTE + look in the specified remote server + --options OPTIONS, -o OPTIONS + Options to build the package, overwriting the defaults. e.g., -o with_qt=true + --settings SETTINGS, -s SETTINGS + Settings to build the package, overwriting the defaults. e.g., -s compiler=gcc + --env ENV, -e ENV Environment variables that will be set during the package build, + e.g. -e CXX=/usr/bin/clang++ + --build [BUILD [BUILD ...]], -b [BUILD [BUILD ...]] + Optional, use it to choose if you want to build from sources: + + --build Build all from sources, do not use binary packages. + --build=never Never build: use binary packages or fail + if a binary package is not found (default). + --build=missing Build from code if a binary package is not found. + --build=outdated Build from code if the binary is not built with the current + recipe or when missing binary package. + --build=[pattern] Always build these packages from source, but never build + the others. Allows multiple --build parameters. + + +**Examples** + +- Install a package requirement from a ``conanfile.txt``, saved in your current directory with one option and setting (other settings will be defaulted as defined in ``/.conan/conan.conf``): + +.. code-block:: bash + + $ conan install . -o use_debug_mode=on -s compiler=clang + + +.. note:: + + You have to take into account that **settings** are cached as defaults in the **conaninfo.txt** file, + so you don't have to type them again and again in the **conan install** or **conan test** + commands. + + However, the default **options** are defined in your **conanfile**. + If you want to change the default options across all your **conan install** commands, change + them in the **conanfile**. When you change the **options** on the command line, they are only changed + for one shot. Next time, **conan install** will take the **conanfile** options as default values, if you + don't specify them again in the command line. + + +- Install the **OpenCV/2.4.10@lasote/testing** reference with its default options and default settings from ``/.conan/conan.conf``: + +.. code-block:: bash + + $ conan install opencv/2.4.10@lasote/testing + + +- Install the **OpenCV/2.4.10@lasote/testing** reference updating the recipe and the binary package if new upstream versions are available: + +.. code-block:: bash + + $ conan install opencv/2.4.10@lasote/testing --update + + +.. _buildoptions: + + +build options +------------- + +Both the conan **install** and **test** commands have options to specify whether conan should +try to build things or not: + +* :command:`--build=never` This is the default option. It is not necessary to write it explicitly. Conan will + not try to build packages when the requested configuration does not match, in which case it will + throw an error. +* :command:`--build=missing` Conan will try to build from source, all packages of which the requested configuration + was not found on any of the active remotes. +* :command:`--build=outdated` Conan will try to build from code if the binary is not built with the current recipe or when missing binary package +* :command:`--build=[pattern]` Conan will force the build of the packages, the name of which matches the given **pattern**. + Several patterns can be specified, chaining multiple options, e.g. :command:`--build=pattern1 --build=pattern2` +* :command:`--build` Always build everything from source. Produces a clean re-build of all packages + and transitively dependent packages + + +env variables +------------- + +With the **-e** parameters you can define: + + - Global environment variables (``-e SOME_VAR="SOME_VALUE"``). These variables will be defined before the `build` step in all the packages and will be cleaned after the `build` execution. + - Specific package environment variables (``-e zlib:SOME_VAR="SOME_VALUE"``). These variables will be defined only in the specified packages (e.g. zlib). + +You can specify this variables not only for your direct ``requires`` but for any package in the dependency graph. + +If you want to define an environment variable but you want to append the variables declared in your +requirements you can use the [] syntax: + +.. code-block:: bash + + conan install -e PYTHONPATH=[/other/path] + +This way the first entry in the PYTHONPATH variable will be `/other/path` but the PYTHONPATH values declared in the requirements +of the project will be appended at the end using the system path separator. + + +settings +-------- + +With the **-s** parameters you can define: + + - Global settings (-s compiler="Visual Studio"). Will apply to all the requires. + - Specific package settings (-s zlib:compiler="MinGW"). Those settings will be applied only to the specified packages. + +You can specify custom settings not only for your direct ``requires`` but for any package in the dependency graph. + + +options +------- + +With the **-o** parameters you can only define specific package options (-o zlib:shared=True). + + +.. note:: + + You can use :ref:`profiles ` files to create predefined sets of **settings**, **options**, **environment variables** and **scopes** diff --git a/reference/commands/new.rst b/reference/commands/new.rst new file mode 100644 index 000000000000..b24b7062d8cc --- /dev/null +++ b/reference/commands/new.rst @@ -0,0 +1,43 @@ + +.. _conan_new: + +conan new +========= + +.. code-block:: bash + + $ conan new [-h] [-t] [-i] [-c] name + + +Creates a new package recipe template with a ``conanfile.py`` and optionally, ``test_package`` +package testing files. + +.. code-block:: bash + + positional arguments: + name Package name, e.g.: Poco/1.7.3@user/testing + + optional arguments: + -h, --help show this help message and exit + -t, --test Create test_package skeleton to test package + -i, --header Create a headers only package template + -c, --pure_c Create a C language package only package, + deleting "self.settings.compiler.libcxx" setting in the configure method + + +**Examples**: + + +- Create a new ``conanfile.py`` for a new package **mypackage/1.0@myuser/stable** + +.. code-block:: bash + + $ conan new mypackage/1.0@myuser/stable + + +- Create also a ``test_package`` folder skeleton: + +.. code-block:: bash + + $ conan new mypackage/1.0@myuser/stable -t + diff --git a/reference/commands/package.rst b/reference/commands/package.rst new file mode 100644 index 000000000000..8e18750044da --- /dev/null +++ b/reference/commands/package.rst @@ -0,0 +1,69 @@ + +conan package +============= + + +.. code-block:: bash + + $ conan package [-h] reference [package] + + +Calls your conanfile.py ``package()`` method for a specific package recipe. +Intended for package creators, for regenerating a package without recompiling +the source, i.e. for troubleshooting, and fixing the ``package()`` method, not +normal operation. + +It requires that the package has been built locally, it won't +re-package otherwise. When used in a user space project, it +will execute from the build folder specified as parameter, and the current +directory. This is useful while creating package recipes or just for +extracting artifacts from the current project, without even being a package + +This command also works locally, in the user space, and it will copy artifacts from the provided +folder to the current one. + +.. code-block:: bash + + positional arguments: + reference package recipe reference e.g. MyPkg/0.1@user/channel, or local + path to the build folder (relative or absolute) + package Package ID to regenerate. e.g., + 9cf83afd07b678d38a9c1645f605875400847ff3 This optional parameter + is only used for the local conan cache. If not specified, ALL binaries + for this recipe are re-packaged + +The ``conan package`` and the ``package()`` method might use dependencies information, either from +``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if +using the ``txt`` generator in the ``conanbuildinfo.txt``. +So, if the ``conan package`` command is to be used, the recommended way to run install would be: + +.. code-block:: bash + + $ conan install .. -g txt + +or adding ``txt`` generator to the consuming conanfile ``generators`` section + + +**Examples** + + +- Copy artifacts from the provided ``build`` folder to the current one: + +.. code-block:: bash + + $ conan package ../build + + +- Copy the artifacts from the build directory to package directory in the local cache: + + +.. code-block:: bash + + $ conan package MyPackage/1.2@user/channel 9cf83afd07b678da9c1645f605875400847ff3 + + +.. note:: + + Conan package command won't create a new package, use ``install`` or ``test_package`` instead for + creating packages in the conan local cache, or ``build`` for conanfile.py in user space. + diff --git a/reference/commands/profile.rst b/reference/commands/profile.rst new file mode 100644 index 000000000000..c7ead8da13d6 --- /dev/null +++ b/reference/commands/profile.rst @@ -0,0 +1,62 @@ +.. _conan_profile_command: + +conan profile +------------- + +.. code-block:: bash + + $ conan profile [-h] {list,show} ... + + +List all the profiles that exist in the ``.conan/profiles`` folder, or show details for a given profile. +The ``list`` subcommand will always use the default user ``.conan/profiles`` folder. But the +``show`` subcommand is able to resolve absolute and relative paths, as well as to map names to +``.conan/profiles`` folder, in the same way as the ``--profile`` install argument. + + +.. code-block:: bash + + positional arguments: + {list,show} sub-command help + list list current profiles + show show the values defined for a profile. Can be a path (relative + or absolute) to a profile file in any location. + + +**Examples** + +- List the profiles: + +.. code-block:: bash + + $ conan profile list + > myprofile1 + > myprofile2 + +- Print profile contents: + +.. code-block:: bash + + $ conan profile show myprofile1 + Profile myprofile1 + [settings] + ... + +- Print profile contents (in the standard directory ``.conan/profiles``): + +.. code-block:: bash + + $ conan profile show myprofile1 + Profile myprofile1 + [settings] + ... + +- Print profile contents (in a custom directory): + +.. code-block:: bash + + $ conan profile show /path/to/myprofile1 + Profile myprofile1 + [settings] + ... + diff --git a/reference/commands/remote.rst b/reference/commands/remote.rst new file mode 100644 index 000000000000..8352e57f0f60 --- /dev/null +++ b/reference/commands/remote.rst @@ -0,0 +1,92 @@ + +conan remote +============ + +.. code-block:: bash + + $ conan remote [-h] {list,add,remove,update,list_ref,add_ref,remove_ref,update_ref} + + +Handles the remote list and the package recipes associated to a remote. + + +.. code-block:: bash + + positional arguments: + {list,add,remove,update,list_ref,add_ref,remove_ref,update_ref} + sub-command help + list list current remotes + add add a remote + remove remove a remote + update update the remote url + list_ref list the package recipes and its associated remotes + add_ref associate a recipe's reference to a remote + remove_ref dissociate a recipe's reference and its remote + update_ref update the remote associated with a package recipe + + optional arguments: + -h, --help show this help message and exit + + +**Examples** + +- List remotes: + +.. code-block:: bash + + $ conan remote list + + conan.io: https://server.conan.io [Verify SSL: True] + local: http://localhost:9300 [Verify SSL: True] + + + +- Add a new remote: + +.. code-block:: bash + + $ conan remote add remote_name remote_url [verify_ssl] + + +Verify SSL option can be True or False (default True). Conan client will verify the SSL certificates. + + +- Remove a remote: + +.. code-block:: bash + + $ conan remote remove remote_name + + +- Update a remote: + +.. code-block:: bash + + $ conan remote update remote_name new_url [verify_ssl] + + +- List the package recipes and its associated remotes: + +.. code-block:: bash + + $ conan remote list_ref + + bzip2/1.0.6@lasote/stable: conan.io + Boost/1.60.0@lasote/stable: conan.io + zlib/1.2.8@lasote/stable: conan.io + + +- Associate a recipe's reference to a remote: + + +.. code-block:: bash + + $ conan remote add_ref package_recipe_ref remote_name + + +- Update the remote associated with a package recipe: + +.. code-block:: bash + + $ conan remote update_ref package_recipe_ref new_remote_name + diff --git a/reference/commands/remove.rst b/reference/commands/remove.rst new file mode 100644 index 000000000000..4b4db85e8b7d --- /dev/null +++ b/reference/commands/remove.rst @@ -0,0 +1,76 @@ + +conan remove +============ + + +.. code-block:: bash + + $ conan remove [-h] [-p [PACKAGES [PACKAGES ...]]] + [-b [BUILDS [BUILDS ...]]] [-s] [-f] [-r REMOTE] + [-q QUERY] + pattern + + +Remove any package recipe or binary matching a pattern. It can also be used to remove +temporary source or build folders in the local conan cache. + +If no remote is specified, the removal will be done by default in the local conan cache. + + +.. code-block:: bash + + positional arguments: + pattern Pattern name, e.g., openssl/* + + optional arguments: + -h, --help show this help message and exit + -p [PACKAGES [PACKAGES ...]], --packages [PACKAGES [PACKAGES ...]] + By default, remove all the packages or select one, + specifying the package ID + -b [BUILDS [BUILDS ...]], --builds [BUILDS [BUILDS ...]] + By default, remove all the build folders or select + one, specifying the package ID + -s, --src Remove source folders + -f, --force Remove without requesting a confirmation + -r REMOTE, --remote REMOTE + Will remove from the specified remote + -q QUERY, --query QUERY + Packages query: "os=Windows AND (arch=x86 OR + compiler=gcc)". The "pattern" parameter has to be a + package recipe reference: MyPackage/1.2@user/channel + + +The ``-q`` parameter can't be used along with ``-p`` nor ``-b`` parameters. + +**Examples**: + +- Remove from the local conan cache the binary packages (the package recipes will not be removed) + from all the recipes matching ``OpenSSL/*`` pattern: + + +.. code-block:: bash + + $ conan remove OpenSSL/* --packages + + +- Remove the temporary build folders from all the recipes matching ``OpenSSL/*`` pattern without requesting confirmation: + +.. code-block:: bash + + $ conan remove OpenSSL/* --builds --force + + +- Remove the recipe and the binary packages from a specific remote: + +.. code-block:: bash + + $ conan remove OpenSSL/1.0.2@lasote/stable -r myremote + + +- Remove only Windows OpenSSL packages from local cache: + +.. code-block:: bash + + $ conan remove OpenSSL/1.0.2@lasote/stable -q "os=Windows" + + diff --git a/reference/commands/search.rst b/reference/commands/search.rst new file mode 100644 index 000000000000..703114feda70 --- /dev/null +++ b/reference/commands/search.rst @@ -0,0 +1,69 @@ +conan search +============ + +.. code-block:: bash + + $ conan search [-r REMOTE] [pattern] + +Search both package recipes and package binaries in the local cache or in a remote server. +If you provide a pattern, then it will search for existing package recipes matching that pattern. + +You can search in a remote or in the local cache, if nothing is specified, the local conan cache is +assumed. + +.. code-block:: bash + + positional arguments: + pattern Pattern name, e.g. openssl/* or package recipe + reference if "-q" is used. e.g. + MyPackage/1.2@user/channel + + optional arguments: + -h, --help show this help message and exit + --case-sensitive Make a case-sensitive search + -r REMOTE, --remote REMOTE + Remote origin + -q QUERY, --query QUERY + Packages query: "os=Windows AND (arch=x86 OR + compiler=gcc)". The "pattern" parameter has to be a + package recipe reference: MyPackage/1.2@user/channel + +**Examples** + + +.. code-block:: bash + + $ conan search OpenCV/* + $ conan search OpenCV/* -r=conan.io + + +If you use instead the full package recipe reference, you can explore the binaries existing for +that recipe, also in a remote or in the local conan cache: + +.. code-block:: bash + + $ conan search Boost/1.60.0@lasote/stable + +A query syntax is allowed to look for specific binaries, you can use ``AND`` and ``OR`` operators and parenthesis, with settings and also options. + +.. code-block:: bash + + $ conan search Boost/1.60.0@lasote/stable -q arch=x86_64 + $ conan search Boost/1.60.0@lasote/stable -q "(arch=x86_64 OR arch=ARM) AND (build_type=Release OR os=Windows)" + + +If you specify a query filter for a setting and the package recipe is not restricted by this setting, will find all packages: + +.. code-block:: python + + class MyRecipe(ConanFile): + settings="arch" + + +.. code-block:: bash + + $ conan search MyRecipe/1.0@lasote/stable -q os=Windows + + +The query above will find all the ``MyRecipe`` binary packages, because the recipe doesn't declare "os" as a setting. + diff --git a/reference/commands/source.rst b/reference/commands/source.rst new file mode 100644 index 000000000000..dcc171b9ff1a --- /dev/null +++ b/reference/commands/source.rst @@ -0,0 +1,59 @@ + +conan source +============ + +.. code-block:: bash + + $ conan source [-h] [-f] [reference] + + +The ``source`` command executes a conanfile.py ``source()`` method, retrieving source code as +defined in the method, both locally, in user space or for a package in the local cache. + + +.. code-block:: bash + + positional arguments: + reference package recipe reference. e.g., MyPackage/1.2@user/channel or + ./my_project/ + + optional arguments: + -h, --help show this help message and exit + -f, --force In the case of local cache, force the removal of the source + folder, then the execution and retrieval of the source code. + Otherwise, if the code has already been retrieved, it will do + nothing. + + +The ``conan source`` and the ``source()`` method might use dependencies information, either from +``cpp_info`` or from ``env_info``. That information is saved in the ``conan install`` step if +using the ``txt`` generator in the ``conanbuildinfo.txt``. +So, if the ``conan source`` command is to be used, the recommended way to run install would be: + +.. code-block:: bash + + $ conan install .. -g txt + +or adding ``txt`` generator to the consuming conanfile ``generators`` section + + +**Examples**: + +- Call a local recipe's source method: In user space, the command will execute a local conanfile.py + ``source()`` method, in the current directory. + +.. code-block:: bash + + $ conan source ../mysource_folder + + +- Call a cached recipe's source method: In the conan local cache, it will execute the recipe ``source()`` , + in the corresponding ``source`` folder, as defined by the local cache layout. + This command is useful for retrieving such source code before launching multiple concurrent package builds, + that could otherwise collide in the source code retrieval process. + +.. code-block:: bash + + $ conan source Pkg/0.2@user/channel + + diff --git a/reference/commands/test_package.rst b/reference/commands/test_package.rst new file mode 100644 index 000000000000..456f4eae5f44 --- /dev/null +++ b/reference/commands/test_package.rst @@ -0,0 +1,88 @@ +.. _conan_test_package_command: + +conan test_package +================== + +.. code-block:: bash + + $ conan test_package [-h] [-ne] [-f FOLDER] [--scope SCOPE] + [--keep-source] [--update] [--profile PROFILE] + [-r REMOTE] [--options OPTIONS] + [--settings SETTINGS] [--env ENV] + [--build [BUILD [BUILD ...]]] + [path] + + + +The ``test_package`` (previously named **test**) command looks for a **test_package subfolder** in the current directory, and builds the +project that is in it. It will typically be a project with a single requirement, pointing to +the ``conanfile.py`` being developed in the current directory. + +This was mainly intended to do a test of the package, not to run unit or integrations tests on the package +being created. Those tests could be launched if desired in the ``build()`` method. +But it can be used for that purpose if desired, there are no real technical constraints. + +The command line arguments are exactly the same as the settings, options, and build parameters +for the ``install`` command, with one small difference: + +In conan test, by default, the ``--build=CurrentPackage`` pattern is automatically appended for the +current tested package. You can always manually specify other build options, like ``--build=never``, +if you just want to check that the current existing package works for the test subproject, without +re-building it. + +You can use the ``conan new`` command with the ``-t`` option to generate a ``test_package`` skeleton. + + +.. code-block:: bash + + positional arguments: + path path to conanfile file, e.g. /my_project/ + + optional arguments: + -ne, --not-export Do not export the conanfile before test execution + -f FOLDER, --folder FOLDER + alternative test folder name + --scope SCOPE, -sc SCOPE + Use the specified scope in the install command + --keep-source, -k Optional. Do not remove the source folder in local cache. + Use for testing purposes only + --update, -u update with new upstream packages, overwriting the local cache if needed. + --profile PROFILE, -pr PROFILE + Apply the specified profile to the install command + -r REMOTE, --remote REMOTE + look in the specified remote server + --options OPTIONS, -o OPTIONS + Options to build the package, overwriting the defaults. e.g., -o with_qt=true + --settings SETTINGS, -s SETTINGS + Settings to build the package, overwriting the defaults. e.g., -s compiler=gcc + --env ENV, -e ENV Environment variables to set during the package build, + e.g. -e CXX=/usr/bin/clang++ + --build [BUILD [BUILD ...]], -b [BUILD [BUILD ...]] + Optional, use it to choose if you want to build from sources: + + --build Build all from sources, do not use binary packages. + --build=never Default option. Never build, use binary packages + or fail if a binary package is not found. + --build=missing Build from code if a binary package is not found. + --build=outdated Build from code if the binary is not built with the + current recipe or when missing binary package. + --build=[pattern] Build always these packages from source, but never build + the others. Allows multiple --build parameters. + + + +If you want to use a different folder name than **test_package**, just use it and pass it to the ``-f folder`` +command line option + +.. code-block:: bash + + $ conan test_package --f my_test_folder + + +This command will run the equivalent to ``conan export /`` where ``user`` and ``channel`` +will be deduced from the values of the requirement in the ``conanfile.py`` inside the test subfolder. +This is very convenient, as if you are running a package test it is extremely likely that you have +just edited the package recipe. If the package recipe is locally modified, it has to be exported again, +otherwise, the package will be tested with the old recipe. If you want to inhibit this ``export``, +you can use the ``-ne, --no-export`` parameter. + diff --git a/reference/commands/upload.rst b/reference/commands/upload.rst new file mode 100644 index 000000000000..1bac54a3f7a8 --- /dev/null +++ b/reference/commands/upload.rst @@ -0,0 +1,73 @@ + +conan upload +============ + +.. code-block:: bash + + $ conan upload [-h] [--package PACKAGE] [--remote REMOTE] [--all] + [--force] [--confirm] [--retry RETRY] + [--retry_wait RETRY_WAIT] + pattern + +Uploads recipes and binary packages from your local cache to a remote server. + +If you use the ``--force`` variable, it won't check the package date. It will override the remote with the local package. + +If you use a pattern instead of a conan recipe reference you can use the ``-c`` or ``--confirm`` option to upload all the matching recipes. + +If you use the ``--retry`` option you can specify how many times should conan try to upload the packages in case of failure. The default is 2. +With ``--retry_wait`` you can specify the seconds to wait between upload attempts. + +If not remote is specified, the first configured remote (by default conan.io, use +``conan remote list`` to list the remotes) will be used. + + +.. code-block:: bash + + positional arguments: + pattern Pattern or package recipe reference, e.g., + "openssl/*", "MyPackage/1.2@user/channel" + + optional arguments: + -h, --help show this help message and exit + --package PACKAGE, -p PACKAGE + package ID to upload + --remote REMOTE, -r REMOTE + upload to this specific remote + --all Upload both package recipe and packages + --force Do not check conan recipe date, override remote with + local + --confirm, -c If pattern is given upload all matching recipes + without confirmation + --retry RETRY In case of fail it will retry the upload again N times + --retry_wait RETRY_WAIT + Waits specified seconds before retry again + + +**Examples**: + +Uploads a package recipe (conanfile.py and the exported files): + +.. code-block:: bash + + $ conan upload OpenCV/1.4.0@lasote/stable + +Uploads a package recipe and all the generated binary packages to a specified remote: + +.. code-block:: bash + + $ conan upload OpenCV/1.4.0@lasote/stable --all -r my_remote + + +Uploads all recipes and binary packages from our local cache to ``my_remote`` without confirmation: + +.. code-block:: bash + + $ conan upload "*" --all -r my_remote -c + +Upload all local packages and recipes beginning with "Op" retrying 3 times and waiting 10 seconds between upload attempts: + +.. code-block:: bash + + $ conan upload "Op*" --all -r my_remote -c --retry 3 --retry_wait 10 + diff --git a/reference/commands/user.rst b/reference/commands/user.rst new file mode 100644 index 000000000000..04a23af6e19f --- /dev/null +++ b/reference/commands/user.rst @@ -0,0 +1,64 @@ +conan user +========== + +.. code-block:: bash + + $ conan user [-h] [-p PASSWORD] [--remote REMOTE] [-c] [name] + +Update your cached user name (and auth token) to avoid it being requested later, e.g. while you're uploading a package. +You can have more than one user (one per remote). Changing the user, or introducing the password is only necessary to upload +packages to a remote. + +.. code-block:: bash + + positional arguments: + name Username you want to use. If no name is provided it + will show the current user. + + optional arguments: + -h, --help show this help message and exit + -p PASSWORD, --password PASSWORD + User password. Use double quotes if password with + spacing, and escape quotes if existing + --remote REMOTE, -r REMOTE + look in the specified remote server + -c, --clean Remove user and tokens for all remotes + + + +**Examples**: + +- List my user for each remote: + +.. code-block:: bash + + $ conan user + + +- Change **conan.io** remote user to **foo**: + +.. code-block:: bash + + $ conan user foo -r conan.io + +- Change **conan.io** remote user to **foo**, authenticating against the remote and storing the + user and authentication token locally, so a later upload won't require entering credentials: + +.. code-block:: bash + + $ conan user foo -r conan.io -p mypassword + +- Clean all local users and tokens + +.. code-block:: bash + + $ conan user --clean + + +.. note:: + + The password is not stored in the client computer at any moment. Conan uses `JWT `: conan + gets a token (expirable by the server) checking the password against the remote credentials. + If the password is correct, an authentication token will be obtained, and that token is the + information cached locally. For any subsequent interaction with the remotes, the conan client will only use that JWT token. + diff --git a/reference/conanfile.rst b/reference/conanfile.rst index d2aaf93a594b..2dda369312e2 100644 --- a/reference/conanfile.rst +++ b/reference/conanfile.rst @@ -1,943 +1,15 @@ -.. _conanfile: +.. _conanfile_reference: +conanfile.py +============ -conanfile -========== +Reference for `conanfile.py`: fields, methods, etc +Contents: -description ------------- -This is an optional, but strongly recommended text field, containing the description of the package, -and any information that might be useful for the consumers. The first line might be used as a -short description of the package. - - -.. code-block:: python - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - description = """This is a Hello World library. - A fully featured, portable, C++ library to say Hello World in the stdout, - with incredible iostreams performance""" - - -.. _package_url: - -url ---- - -It is possible, even typical, if you are packaging a thid party lib, that you just develop -the packaging code. Such code is also subject to change, often via collaboration, so it should be stored -in a VCS like git, and probably put on GitHub or a similar service. If you do indeed maintain such a -repository, please indicate it in the ``url`` attribute, so that it can be easily found. - -.. code-block:: python - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - url = "https://github.com/memsharded/hellopack.git" - - -The ``url`` is the url **of the package** repository, i.e. not necessarily the original source code. -It is optional, but highly recommended, that it points to GitHub, Bitbucket or your preferred -code collaboration platform. Of course, if you have the conanfile inside your library source, -you can point to it, and afterwards use the ``url`` in your ``source()`` method. - -This is a recommended, but not mandatory attribute. - -license ---------- -This field is intended for the license of the **target** source code and binaries, i.e. the code -that is being packaged, not the ``conanfile.py`` itself. This info is used to be displayed by -the ``conan info`` command and possibly other search and report tools. - -.. code-block:: python - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - license = "MIT" - -This attribute can contain several, comma separated licenses. It is a text string, so it can -contain any text, including hyperlinks to license files elsewhere. - -This is a recommended, but not mandatory attribute. - -author ------- - -Intended to add information about the author, in case it is different from the conan user. It is -possible that the conan user is the name of an organization, project, company or group, and many -users have permissions over that account. In this case, the author information can explicitely -define who is the creator/maintainer of the package - -.. code-block:: python - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - author = "John J. Smith (john.smith@company.com)" - -This is an optional attribute - -.. _user_channel: - -user, channel --------------- - -The fields ``user`` and ``channel`` can be accessed from within a ``conanfile.py``. -Though their usage is usually not encouraged, it could be useful in different cases, -e.g. to define requirements with the same user and -channel than the current package, which could be achieved with something like: - -.. code-block:: python - - from conans import ConanFile - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - - def requirements(self): - self.requires("Say/0.1@%s/%s" % (self.user, self.channel)) - - -Only package recipes that are in the conan local cache (i.e. "exported") have an user/channel assigned. -For package recipes working in user space, there is no current user/channel. The properties ``self.user`` -and ``self.channel`` will then look for environment variables ``CONAN_USERNAME`` and ``CONAN_CHANNEL`` -respectively. If they are not defined, an error will be raised. - - -.. _settings_property: - -settings ----------- - -There are several things that can potentially affect a package being created, i.e. the final -package will be different (a different binary, for example), if some input is different. - -Development project-wide variables, like the compiler, its version, or the OS -itself. These variables have to be defined, and they cannot have a default value listed in the -conanfile, as it would not make sense. - -It is obvious that changing the OS produces a different binary in most cases. Changing the compiler -or compiler version changes the binary too, which might have a compatible ABI or not, but the -package will be different in any case. - -But what happens for example to **header only libraries**? The final package for such libraries is not -binary and, in most cases it will be identical, unless it is automatically generating code. -We can indicate that in the conanfile: - -.. code-block:: python - - from conans import ConanFile - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - # We can just omit the settings attribute too - settings = None - - def build(self): - #empty too, nothing to build in header only - - -You can restrict existing settings and accepted values as well, by redeclaring the settings -attribute: - -.. code-block:: python - - class HelloConan(ConanFile): - settings = {"os": ["Windows"], - "compiler": {"Visual Studio": {"version": [11, 12]}}, - "arch": None} - -In this example we have just defined that this package only works in Windows, with VS 10 and 11. -Any attempt to build it in other platforms with other settings will throw an error saying so. -We have also defined that the runtime (the MD and MT flags of VS) is irrelevant for us -(maybe we using a universal one?). Using None as a value means, *maintain the original values* in order -to avoid re-typing them. Then, "arch": None is totally equivalent to "arch": ["x86", "x86_64", "arm"] -Check the reference or your ~/.conan/settings.yml file. - -As re-defining the whole settings attribute can be tedious, it is sometimes much simpler to -remove or tune specific fields in the ``config()`` method. For example, if our package is runtime -independent in VS, we can just remove that setting field: - - -.. code-block:: python - - settings = "os", "compiler", "build_type", "arch" - - def config(self): - self.settings.compiler["Visual Studio"].remove("runtime") - -.. _conanfile_options: - -options, default_options ---------------------------- -Options are similar to settings in the sense that they influence the final package. But they -can typically have a default value. A very common case would be the static/shared option of -a compiled library, which could be defined as: - - -.. code-block:: python - - class HelloConan(ConanFile): - ... - options = {"static": [True, False]} - default_options = "static=True" - - def build(self): - static = "-DBUILD_SHARED_LIBS=ON" if not self.options.static else "" - cmake = CMake(self.settings) - self.run("cmake . %s %s" % (cmake.command_line, static)) - self.run("cmake --build . %s" % cmake.build_config) - -Note that you have to consider the option properly in your build. In this case, we are using -the CMake way. You must also remove the **STATIC** linkage in the **CMakeLists.txt** file, -and if you are using VS, you also need to change your code to correctly import/export symbols -for the dll. - -You can use the ``ANY`` string to allow any value for a specified option. The range of values for -such an option will not be checked, and any value (as string) will be accepted. - -.. code-block:: python - - class HelloConan(ConanFile): - ... - options = {"commit": "ANY"} - default_options = "commit=1234abcd" - -This could be useful, for example, if you want to have an option so a package can actually reference any specific -commit of a git repository. - -You can also specify options of the package dependencies: - -.. code-block:: python - - class HelloConan(ConanFile): - requires = "Pkg/0.1@user/channel" - default_options = "Pkg:pkg_option=value" - -If you need to dynamically set some dependency options, you could do: - -.. code-block:: python - - class HelloConan(ConanFile): - requires = "Pkg/0.1@user/channel" - - def configure(self): - self.options["Pkg"].pkg_option = "value" - -requires ---------- - -Specify package dependencies as a list of other packages: - - -.. code-block:: python - - class MyLibConan(ConanFile): - requires = "Hello/1.0@user/stable", "OtherLib/2.1@otheruser/testing" - -You can specify further information about the package requirements: - -.. code-block:: python - - class MyLibConan(ConanFile): - requires = (("Hello/0.1@user/testing"), - ("Say/0.2@dummy/stable", "override"), - ("Bye/2.1@coder/beta", "private")) - -Requirements can be complemented by 2 different parameters: - -**private**: a dependency can be declared as private if it is going to be fully embedded and hidden -from consumers of the package. Typical examples could be a header only library which is not exposed -through the public interface of the package, or the linking of a static library inside a dynamic -one, in which the functionality or the objects of the linked static library are not exposed through -the public interface of the dynamic library. - -**override**: packages can define overrides of their dependencies, if they require the definition of -specific versions of the upstream required libraries, but not necessarily direct dependencies. For example, -a package can depend on A(v1.0), which in turn could conditionally depend on Zlib(v2), depending on whether -the compression is enabled or not. Now, if you want to force the usage of Zlib(v3) you can: - -.. code-block:: python - - class HelloConan(ConanFile): - requires = ("A/1.0@user/stable", ("Zlib/3.0@other/beta", "override")) - - -This **will not introduce a new dependency**, it will just change Zlib v2 to v3 if A actually -requires it. Otherwise Zlib will not be a dependency of your package. - -.. _version_ranges: - -version ranges -++++++++++++++ - -From conan 0.16, version ranges expressions are supported, both in ``conanfile.txt`` and in -``conanfile.py`` requirements. The syntax is using brackets: - -.. code-block:: python - - class HelloConan(ConanFile): - requires = "Pkg/[>1.0,<1.8]@user/stable" - -Expressions are those defined and implemented by [python node-semver](https://pypi.python.org/pypi/node-semver), -but using a comma instead of spaces. Accepted expressions would be: - -.. code-block:: python - - >1.1,<2.1 # In such range - 2.8 # equivalent to =2.8 - ~=3.0 # compatible, according to semver - >1.1 || 0.8 # conditions can be OR'ed - -Version ranges expressions are evaluated at the time of building the dependencies graph, from -downstream to upstream dependencies. No joint-compatibility of the full graph is computed, instead, -version ranges are evaluated when dependencies are first retrieved. - -This means, that if a package A, depends on another package B (A->B), and A has a requirement for -``C/[>1.2,<1.8]``, this requirements is evaluated first and it can lead to get the version ``C/1.7``. If -package B has the requirement to ``C/[>1.3,<1.6]``, this one will be overwritten by the downstream one, -it will output a version incompatibility error. But the "joint" compatibility of the graph will not -be obtained. Downstream packages or consumer projects can impose their own requirements to comply -with upstream constraints, in this case a override dependency to ``C/[>1.3,<1.6]`` can be easily defined -in the downstream package or project. - -The order of search for matching versions is as follows: - -- First, the local conan storage is searched for matching versions, unless the ``--update`` flag - is provided to ``conan install`` -- If a matching version is found, it is used in the dependency graph as a solution -- If no matching version is locally found, it starts to search in the remotes, in order. If some - remote is specified with ``-r=remote``, then only that remote will be used. -- If the ``--update`` parameter is used, then the existing packages in the local conan cache will - not be used, and the same search of the previous steps is carried out in the remotes. If new - matching versions are found, they will be retrieved, so subsequents call to ``install`` will - find them locally and use them. - - -exports --------- -If a package recipe ``conanfile.py`` requires other external files, like other python files that -it is importing (python importing), or maybe some text file with data it is reading, those files -must be exported with the ``exports`` field, so they are stored together, side by side with the -``conanfile.py`` recipe. - -The ``exports`` field can be one single pattern, like ``exports="*"``, or several inclusion patterns. -For example, if we have some python code that we want the recipe to use in a ``helpers.py`` file, -and have some text file, ``info.txt``, we want to read and display during the recipe evaluation -we would do something like: - -.. code-block:: python - - exports = "helpers.py", "info.txt" - -This is an optional attribute, only to be used if the package recipe requires these other files -for evaluation of the recipe. - -exports_sources ----------------- -There are 2 ways of getting source code to build a package. Using the ``source()`` recipe method -and using the ``exports_sources`` field. With ``exports_sources`` you specify which sources are required, -and they will be exported together with the **conanfile.py**, copying them from your folder to the -local conan cache. Using ``exports_sources`` -the package recipe can be self-contained, containing the source code like in a snapshot, and then -not requiring downloading or retrieving the source code from other origins (git, download) with the -``source()`` method when it is necessary to build from sources. - -The ``exports_sources`` field can be one single pattern, like ``exports_sources="*"``, or several inclusion patterns. -For example, if we have the source code inside "include" and "src" folders, and there are other folders -that are not necessary for the package recipe, we could do: - -.. code-block:: python - - exports_sources = "include*", "src*" - -This is an optional attribute, used typically when ``source()`` is not specify. The main difference with -``exports`` is that ``exports`` files are always retrieved (even if pre-compiled packages exist), -while ``exports_sources`` files are only retrieved when it is necessary to build a package from sources. - -generators ----------- - -Generators specify which is the output of the ``install`` command in your project folder. By -default, a ``conanbuildinfo.txt`` file is generated, but you can specify different generators: - -- **gcc**: conanbuildinfo.gcc -- **cmake**: conanbuildinfo.cmake -- **txt**: conanbuildinfo.txt -- **qmake**: conanbuildinfo.pri -- **qbs**: conanbuildinfo.qbs -- **visual_studio**: conanbuildinfo.props -- **xcode**: conanbuildinfo.xcconfig - -You can specify more than one: - -.. code-block:: python - - class MyLibConan(ConanFile): - generators = "cmake", "gcc" - -build_policy --------------- - -With the ``build_policy`` attribute the package creator can change the default conan's build behavior. -The allowed ``build_policy`` values are: - -- ``missing``: If no binary package is found, conan will build it without the need of invoke conan install with **--build missing** option. -- ``always``: The package will be built always, **retrieving each time the source code** executing the "source" method. - - -.. code-block:: python - :emphasize-lines: 2 - - class PocoTimerConan(ConanFile): - build_policy = "always" # "missing" - -short_paths ------------- - -If one of the packages you are creating hits the limit of 260 chars path length in Windows, add -``short_paths=True`` in your conanfile.py: - -.. code-block:: python - - from conans import ConanFile - - class ConanFileTest(ConanFile): - ... - short_paths = True - -This will automatically "link" the ``source`` and ``build`` directories of the package to the drive root, -something like `C:/.conan/tmpdir`. All the folder layout in the conan cache is maintained. - -This attribute will not have any effect in other OS, it will be discarded. - -From Windows 10 (ver. 10.0.14393), it is possible to opt-in disabling the path limits. Check `this link -`_ for more info. Latest python installers might offer to enable this while installing python. With this limit removed, the ``short_paths`` functionality is totally unnecessary. - - -.. _retrieve_source: - -source() --------- - -The other way is to let conan retrieve the source code from any other external origin, github, or -just a regular download. This can be done in the ``source()`` method. - -For example, in the previous section, we "exported" the source code files, together with the **conanfile.py** file, -which can be handy if the source code is not under version control. But if the source code is available in a repository, -you can directly get it from there: - -.. code-block:: python - - from conans import ConanFile - - class HelloConan(ConanFile): - name = "Hello" - version = "0.1" - settings = "os", "compiler", "build_type", "arch" - - def source(self): - self.run("git clone https://github.com/memsharded/hello.git") - # You can also change branch, commit or whatever - # self.run("cd hello && git checkout 2fe5...") - - -This will work, as long as ``git`` is in your current path (so in Win you probably want to run things in msysgit, cmder, etc). -You can also use another VCS or direct download/unzip. For that purpose, we have provided some helpers, -but you can use your own code or origin as well. This is a snippet of the conanfile of the POCO libray: - - -.. code-block:: python - - from conans import ConanFile - from conans.tools import download, unzip, check_md5, check_sha1, check_sha256 - import os - import shutil - - class PocoConan(ConanFile): - name = "Poco" - version = "1.6.0" - - def source(self): - zip_name = "poco-1.6.0-release.zip" - download("https://github.com/pocoproject/poco/archive/poco-1.6.0-release.zip", zip_name) - # check_md5(zip_name, "51e11f2c02a36689d6ed655b6fff9ec9") - # check_sha1(zip_name, "8d87812ce591ced8ce3a022beec1df1c8b2fac87") - # check_sha256(zip_name, "653f983c30974d292de58444626884bee84a2731989ff5a336b93a0fef168d79") - unzip(zip_name) - shutil.move("poco-poco-1.6.0-release", "poco") - os.unlink(zip_name) - -The download, unzip utilities can be imported from conan, but you can also use your own code here -to retrieve source code from any origin. You can even create packages for pre-compiled libraries -you already have, even if you don't have the source code. You can download the binaries, skip -the ``build()`` method and define your ``package()`` and ``package_info()`` accordingly. - -You can also use **check_md5**, **check_sha1** and **check_sha256** from the **tools** module to verify that a package is downloaded correctly. - -build() --------- - -Build helpers -+++++++++++++ - -You can use these classes to prepare your build system's command invocation: - -- **CMake**: Prepares the invocation of cmake command with your settings. -- **AutoToolsBuildEnvironment**: If you are using configure/Makefile to build your project you can use this helper. - Read more: :ref:`Building with Autotools `. -- **VisualStudioBuildEnvironment**: If you are calling your Visual Studio compiler directly to build your project you can use this helper. - Read more: :ref:`Building with Visual Studio `. -- **tools.build_sln_command()**: If you have an ``sln`` project you can use this tool to build it. - Read more: :ref:`Build an existing Visual Studio project `. -- **GCC generator**: If you are calling GCC or Clang directly to build your project you can use the ``gcc`` generator. - Read more: :ref:`Building with GCC or Clang `. - - - -(Unit) Testing your library -++++++++++++++++++++++++++++ -We have seen how to run package tests with conan, but what if we want to run full unit tests on -our library before packaging, so that they are run for every build configuration? -Nothing special is required here. We can just launch the tests from the last command in our -``build()`` method: - -.. code-block:: python - - def build(self): - cmake = CMake(self.settings) - self.run("cmake . %s %s" % (cmake.command_line)) - self.run("cmake --build . %s" % cmake.build_config) - # here you can run CTest, launch your binaries, etc - self.run("ctest") - - -package() ---------- -The actual creation of the package, once that it is build, is done in the ``package()`` method. -Using the ``self.copy()`` method, artifacts are copied from the build folder to the package folder. -The syntax of copy is as follows: - -.. code-block:: python - - self.copy(pattern, dst, src, keep_path=False) - - -- ``pattern`` is a pattern following fnmatch syntax of the files you want to copy, from the *build* to the *package* folders. Typically something like ``*.lib`` or ``*.h`` -- ``dst`` is the destination folder in the package. They will typically be ``include`` for headers, ``lib`` for libraries and so on, though you can use any convention you like -- ``src`` is the folder where you want to search the files in the *build* folder. If you know that your libraries when you build your package will be in *build/lib*, you will typically use ``build/lib`` in this parameter. Leaving it empty means the root build folder. -- ``keep_path``, with default value=True, means if you want to keep the relative path when you copy the files from the source(build) to the destination(package). Typically headers, you keep the relative path, so if the header is in *build/include/mylib/path/header.h*, you write: -- ``links``, with default value=False, you can activate it to copy symlinks, like typical lib.so->lib.so.9 - - -.. code-block:: python - - self.copy("*.h", "include", "build/include") #keep_path default is True - -so the final path in the package will be: ``include/mylib/path/header.h``, and as the *include* is usually added to the path, the includes will be in the form: ``#include "mylib/path/header.h"`` which is something desired - -``keep_path=False`` is something typically desired for libraries, both static and dynamic. Some compilers as MSVC, put them in paths as *Debug/x64/MyLib/Mylib.lib*. Using this option, we could write: - -.. code-block:: python - - self.copy("*.lib", "lib", "", keep_path=False) - - -And it will copy the lib to the package folder *lib/Mylib.lib*, which can be linked easily - -.. note:: - - If you are using CMake and you have an install target defined in your CMakeLists.txt, you - might be able to reuse it for this ``package()`` method. Please check :ref:`reuse_cmake_install` - - -.. _package_info: - -package_info() ---------------- - -cpp_info -+++++++++ -Each package has to specify certain build information for its consumers. This can be done in -the ``cpp_info`` attribute within the ``package_info()`` method. - -The ``cpp_info`` attribute has the following properties you can assign/append to: - -.. code-block:: python - - self.cpp_info.includedirs = ['include'] # Ordered list of include paths - self.cpp_info.libs = [] # The libs to link against - self.cpp_info.libdirs = ['lib'] # Directories where libraries can be found - self.cpp_info.resdirs = ['res'] # Directories where resources, data, etc can be found - self.cpp_info.bindirs = [] # Directories where executables and shared libs can be found - self.cpp_info.defines = [] # preprocessor definitions - self.cpp_info.cflags = [] # pure C flags - self.cpp_info.cppflags = [] # C++ compilation flags - self.cpp_info.sharedlinkflags = [] # linker flags - self.cpp_info.exelinkflags = [] # linker flags - - -* includedirs: list of relative paths (starting from the package root) of directories where headers - can be found. By default it is initialized to ['include'], and it is rarely changed. -* libs: ordered list of libs the client should link against. Empty by default, it is common - that different configurations produce different library names. For example: - -.. code-block:: python - - def package_info(self): - if not self.settings.os == "Windows": - self.cpp_info.libs = ["libzmq-static.a"] if self.options.static else ["libzmq.so"] - else: - ... - -* libdirs: list of relative paths (starting from the package root) of directories in which to find - library object binaries (.lib, .a, .so. dylib). By default it is initialize to ['lib'], and it is rarely changed. -* resdirs: list of relative paths (starting from the package root) of directories in which to find - resource files (images, xml, etc). By default it is initialize to ['res'], and it is rarely changed. -* bindirs: list of relative paths (starting from the package root) of directories in which to find - library runtime binaries (like windows .dlls). By default it is initialized to ['bin'], and it is rarely changed. -* defines: ordered list of preprocessor directives. It is common that the consumers have to specify - some sort of defines in some cases, so that including the library headers matches the binaries: -* flags, list of flags that the consumer should activate for proper - behavior. Usage of C++11 could be configured here, for example, although it is true that the consumer may - want to do some flag processing to check if different dependencies are setting incompatible flags - (c++11 after c++14) - -.. code-block:: python - - if self.options.static: - if self.settings.compiler == "Visual Studio": - self.cpp_info.libs.append("ws2_32") - self.cpp_info.defines = ["ZMQ_STATIC"] - - if not self.settings.os == "Windows": - self.cpp_info.cppflags = ["-pthread"] - - -.. _environment_information: - -env_info -+++++++++ - -Each package can also define some environment variables that the package needs to be reused. -It's specially useful for :ref:`installer packages`, to set the path with the "bin" folder of the packaged application. -This can be done in the ``env_info`` attribute within the ``package_info()`` method. - -.. code-block:: python - - self.env_info.path.append("ANOTHER VALUE") # Append "ANOTHER VALUE" to the path variable - self.env_info.othervar = "OTHER VALUE" # Assign "OTHER VALUE" to the othervar variable - self.env_info.thirdvar.append("some value") # Every variable can be set or appended a new value - - -The :ref:`virtualenv` generator will use the self.env_info variables to prepare a script to activate/deactive a virtual environment. - -In previous conan versions you needed to use `ConfigureEnvironment` helper (now deprecated) to reuse these variables, but it's not needed anymore. -They will be automatically applied before calling the consumer conanfile.py methods `source`, `build`, `package` and `imports`. - - -configure(), config_options() ------------------------------ - -Note: ``config()`` method has been deprecated, used ``configure()`` instead. - -If the package options and settings are related, and you want to configure either, you can do so -in the ``configure()`` and ``config_options()`` methods. This is an example: - -.. code-block:: python - - class MyLibConan(ConanFile): - name = "MyLib" - version = "2.5" - settings = "os", "compiler", "build_type", "arch" - options = {"static": [True, False], - "header_only": [True False]} - - def config(self): - # If header only, the compiler, etc, does not affect the package! - if self.options.header_only: - self.settings.clear() - self.options.remove("static") - -The package has 2 options set, to be compiled as a static (as opposed to shared) library, -and also not to involve any builds, because header-only libraries will be used. In this case, -the settings that would affect a normal build, and even the other option (static vs shared) -do not make sense, so we just clear them. That means, if someone consumes MyLib with the -``header_only: True`` option, the package downloaded and used will be the same, irrespective of -the OS, compiler or architecture the consumer is building with. - -The most typical usage would be the one with ``configure()`` while ``config_options()`` should be -used more sparingly. ``config_options()`` is used to configure or constraint the available -options in a package, **before** they are given a value. So when a value is tried to be assigned, -it will raise an error. For example, let's suppose that a certain package library cannot be -built as shared library in Windows, it can be done: - -.. code-block:: python - - def config_options(self): - if self.settings.os == "Windows": - del self.options.shared - -This will be executed before the actual assignment of ``options`` (then, such ``options`` values -cannot be used inside this function), so the command ``$ conan install -o Pkg:shared=True`` will -raise an Exception in Windows saying that ``shared`` is not an option for such package. - - -requirements() --------------- - -Besides the ``requires`` field, more advanced requirement logic can be defined in the -``requirements()`` optional method, using for example values from the package ``settings`` or -``options``: - - -.. code-block:: python - - def requirements(self): - if self.options.myoption: - self.requires("zlib/1.2@drl/testing") - else: - self.requires("opencv/2.2@drl/stable") - -This is a powerful mechanism for handling **conditional dependencies**. - -When you are inside the method, each call to ``self.requires()`` will add the corresponding -requirement to the current list of requirements. It also has optional parameters that allow -defining the special cases, as is shown below: - -.. code-block:: python - - def requirements(self): - self.requires("zlib/1.2@drl/testing", private=True, override=False) - -.. _system_requirements: - -system_requirements() ----------------------- -It is possible to install system-wide packages from conan. Just add a ``system_requirements()`` -method to your conanfile and specify what you need there. - -You can use ``conans.tools.os_info`` object to detect the operating system, version and distribution (linux): - -- ``os_info.is_linux`` True if Linux -- ``os_info.is_windows`` True if Windows -- ``os_info.is_macos`` True if OSx -- ``os_info.os_version`` OS version -- ``os_info.os_version_name`` Common name of the OS (Windows 7, Mountain Lion, Wheezy...) -- ``os_info.linux_distro`` Linux distribution name (None if not Linux) - -Also you can use ``SystemPackageTool`` class, that will automatically invoke the right system package tool: **apt**, **yum** or **brew** depending on the system we are running. - -.. code-block:: python - - from conans.tools import os_info, SystemPackageTool - - def system_requirements(self): - pack_name = None - if os_info.linux_distro == "ubuntu": - if os_info.os_version > "12": - pack_name = "package_name_in_ubuntu_10" - else: - pack_name = "package_name_in_ubuntu_12" - elif os_info.linux_distro == "fedora" or os_info.linux_distro == "centos": - pack_name = "package_name_in_fedora_and_centos" - elif os_info.is_macos: - pack_name = "package_name_in_macos" - - if pack_name: - installer = SystemPackageTool() - installer.install(pack_name) # Install the package, will update the package database if pack_name isn't already installed - - -SystemPackageTool methods: - -- **update()**: Updates the system package manager database. It's called automatically from the ``install()`` method by default. -- **install(packages, update=True, force=False)**: Installs the ``packages`` (could be a list or a string). If ``update`` is True it will - execute ``update()`` first if it's needed. The packages won't be installed if they are already installed at least of ``force`` - parameter is set to True. If ``packages`` is a list the first available package will be picked (short-circuit like logical **or**). - - -The use of ``sudo`` in the internals of the ``install()`` and ``update()`` methods is controlled by the CONAN_SYSREQUIRES_SUDO -environment variable, so if the users don't need sudo permissions, it is easy to opt-in/out. - -Conan will keep track of the execution of this method, so that it is not invoked again and again -at every conan command. The execution is done per package, since some packages of the same -library might have different system dependencies. If you are sure that all your binary packages -have the same system requirements, just add the following line to your method: - -.. code-block:: python - - def system_requirements(self): - self.global_system_requirements=True - if ... - - - -imports() ---------------- -Importing files copies files from the local store to your project. This feature is handy -for copying shared libraries (dylib in Mac, dll in Win) to the directory of your executable, so that you don't have -to mess with your PATH to run them. But there are other use cases: - -- Copy an executable to your project, so that it can be easily run. A good example is the google - **protobuf** code generator, go to the examples section to check it out. -- Copy package data to your project, like configuration, images, sounds... A good example is the - OpenCV demo, in which face detection XML pattern files are required. - -Importing files is also very convenient in order to redistribute your application, as many times -you will just have to bundle your project's bin folder. - -A typical ``imports()`` method for shared libs could be: - -.. code-block:: python - - def imports(self): - self.copy("*.dll", "", "bin") - self.copy("*.dylib", "", "lib") - -conan_info() ------------- - -Deprecated, use ``package_id()`` method instead. - - -package_id() ------------- - -Conan keeps the compatibility between binary packages using ``settings``. -When a recipe author specifies some settings in the :ref:`settings_property` property, is telling that any change at any -of those settings will require a different binary package. - -But sometimes you would need to alter the general behavior, for example, to have only one binary package for several different compiler versions. - -Please, check the section :ref:`how_to_define_abi_compatibility` to get more details. - -.. _build_id: - -build_id() ------------- - -In the general case, there is one build folder for each binary package, with the exact same hash/ID -of the package. However this behavior can be changed, there are a couple of scenarios that this might -be interesting: - -- You have a build script that generates several different configurations at once, like both debug - and release artifacts, but you actually want to package and consume them separately. Same for - different architectures or any other setting -- You build just one configuration (like release), but you want to create different binary packages - for different consuming cases. For example, if you have created tests for the library in the build - step, you might want to create to package, one just containing the library for general usage, but - another one also containing the tests, as a reference and a tool to debug errors. - -In both cases, if using different settings, the system will build twice (or more times) the same binaries, -just to produce a different final binary package. With the ``build_id()`` method this logic can be -changed. ``build_id()`` will create a new package ID/hash for the build folder, and you can define -the logic you want in it, for example: - -.. code-block:: python - - settings = "os", "compiler", "arch", "build_type" - - def build_id(self): - self.info_build.settings.build_type = "Any" - - -So this recipe will generate a final different package for each debug/release configuration. But -as the ``build_id()`` will generate the same ID for any ``build_type``, then just one folder and -one build will be done. Such build should build both debug and release artifacts, and then the -``package()`` method should package them accordingly to the ``self.settings.build_type`` value. -Still different builds will be executed if using different compilers or architectures. This method -is basically an optimization of build time, avoiding multiple re-builds. - -Other information as custom package options can also be changed: - -.. code-block:: python - - def build_id(self): - self.info_build.options.myoption = 'MyValue' # any value possible - self.info_build.options.fullsource = 'Always' - - -Other ------- - -There are some helpers in the conanfile for colored output and running commands: - -.. code-block:: python - - self.output.success("This is a good, should be green") - self.output.info("This is a neutral, should be white") - self.output.warn("This is a warning, should be yellow") - self.output.error("Error, should be red") - self.output.rewrite_line("for progress bars, issues a cr") - -Check the source code. You might be able to produce different outputs with different colors. - - -``self.run()`` is a helper to run system commands and throw exceptions when errors occur, -so that command errors are do not pass unnoticed. It is just a wrapper for ``os.system()`` - -``self.conanfile_directory`` is a property that returns the directory in which the conanfile is -located. - -.. _split_conanfile: - -Splitting conanfile.py ------------------------ -If you want to reuse common functionality between different packages, it can be written in their -own python files and imported from the main ``conanfile.py``. Lets write for example a ``msgs.py`` -file and put it besides the ``conanfile.py``: - -.. code-block:: python - - def build_msg(output): - output.info("Building!") - -And then the main ``conanfile.py`` would be: - -.. code-block:: python - - from conans import ConanFile - from msgs import build_msg - - class ConanFileToolsTest(ConanFile): - name = "test" - version = "1.9" - exports = "msgs.py" # Important to remember! - - def build(self): - build_msg(self.output) - # ... - - -It is important to note that such ``msgs.py`` file **must be exported** too when exporting the package, -because package recipes must be self-contained. - -The code reuse can also be done in the form of a base class, something like a file ``base_conan.py`` - -.. code-block:: python - - from conans import ConanFile - - class ConanBase(ConanFile): - # common code here - -And then: - -.. code-block:: python - - from conans import ConanFile - from base_conan import ConanBase - - class ConanFileToolsTest(ConanBase): - name = "test" - version = "1.9" - +.. toctree:: + :maxdepth: 2 + conanfile/attributes + conanfile/methods + conanfile/other diff --git a/reference/conanfile/attributes.rst b/reference/conanfile/attributes.rst new file mode 100644 index 000000000000..ddfc665d56b3 --- /dev/null +++ b/reference/conanfile/attributes.rst @@ -0,0 +1,421 @@ +Attributes +========== + + +description +------------ +This is an optional, but strongly recommended text field, containing the description of the package, +and any information that might be useful for the consumers. The first line might be used as a +short description of the package. + + +.. code-block:: python + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + description = """This is a Hello World library. + A fully featured, portable, C++ library to say Hello World in the stdout, + with incredible iostreams performance""" + + +.. _package_url: + +url +--- + +It is possible, even typical, if you are packaging a thid party lib, that you just develop +the packaging code. Such code is also subject to change, often via collaboration, so it should be stored +in a VCS like git, and probably put on GitHub or a similar service. If you do indeed maintain such a +repository, please indicate it in the ``url`` attribute, so that it can be easily found. + +.. code-block:: python + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + url = "https://github.com/memsharded/hellopack.git" + + +The ``url`` is the url **of the package** repository, i.e. not necessarily the original source code. +It is optional, but highly recommended, that it points to GitHub, Bitbucket or your preferred +code collaboration platform. Of course, if you have the conanfile inside your library source, +you can point to it, and afterwards use the ``url`` in your ``source()`` method. + +This is a recommended, but not mandatory attribute. + +license +--------- +This field is intended for the license of the **target** source code and binaries, i.e. the code +that is being packaged, not the ``conanfile.py`` itself. This info is used to be displayed by +the ``conan info`` command and possibly other search and report tools. + +.. code-block:: python + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + license = "MIT" + +This attribute can contain several, comma separated licenses. It is a text string, so it can +contain any text, including hyperlinks to license files elsewhere. + +This is a recommended, but not mandatory attribute. + +author +------ + +Intended to add information about the author, in case it is different from the conan user. It is +possible that the conan user is the name of an organization, project, company or group, and many +users have permissions over that account. In this case, the author information can explicitely +define who is the creator/maintainer of the package + +.. code-block:: python + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + author = "John J. Smith (john.smith@company.com)" + +This is an optional attribute + +.. _user_channel: + +user, channel +-------------- + +The fields ``user`` and ``channel`` can be accessed from within a ``conanfile.py``. +Though their usage is usually not encouraged, it could be useful in different cases, +e.g. to define requirements with the same user and +channel than the current package, which could be achieved with something like: + +.. code-block:: python + + from conans import ConanFile + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + + def requirements(self): + self.requires("Say/0.1@%s/%s" % (self.user, self.channel)) + + +Only package recipes that are in the conan local cache (i.e. "exported") have an user/channel assigned. +For package recipes working in user space, there is no current user/channel. The properties ``self.user`` +and ``self.channel`` will then look for environment variables ``CONAN_USERNAME`` and ``CONAN_CHANNEL`` +respectively. If they are not defined, an error will be raised. + + +.. _settings_property: + +settings +---------- + +There are several things that can potentially affect a package being created, i.e. the final +package will be different (a different binary, for example), if some input is different. + +Development project-wide variables, like the compiler, its version, or the OS +itself. These variables have to be defined, and they cannot have a default value listed in the +conanfile, as it would not make sense. + +It is obvious that changing the OS produces a different binary in most cases. Changing the compiler +or compiler version changes the binary too, which might have a compatible ABI or not, but the +package will be different in any case. + +But what happens for example to **header only libraries**? The final package for such libraries is not +binary and, in most cases it will be identical, unless it is automatically generating code. +We can indicate that in the conanfile: + +.. code-block:: python + + from conans import ConanFile + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + # We can just omit the settings attribute too + settings = None + + def build(self): + #empty too, nothing to build in header only + + +You can restrict existing settings and accepted values as well, by redeclaring the settings +attribute: + +.. code-block:: python + + class HelloConan(ConanFile): + settings = {"os": ["Windows"], + "compiler": {"Visual Studio": {"version": [11, 12]}}, + "arch": None} + +In this example we have just defined that this package only works in Windows, with VS 10 and 11. +Any attempt to build it in other platforms with other settings will throw an error saying so. +We have also defined that the runtime (the MD and MT flags of VS) is irrelevant for us +(maybe we using a universal one?). Using None as a value means, *maintain the original values* in order +to avoid re-typing them. Then, "arch": None is totally equivalent to "arch": ["x86", "x86_64", "arm"] +Check the reference or your ~/.conan/settings.yml file. + +As re-defining the whole settings attribute can be tedious, it is sometimes much simpler to +remove or tune specific fields in the ``config()`` method. For example, if our package is runtime +independent in VS, we can just remove that setting field: + + +.. code-block:: python + + settings = "os", "compiler", "build_type", "arch" + + def config(self): + self.settings.compiler["Visual Studio"].remove("runtime") + +.. _conanfile_options: + +options, default_options +--------------------------- +Options are similar to settings in the sense that they influence the final package. But they +can typically have a default value. A very common case would be the static/shared option of +a compiled library, which could be defined as: + + +.. code-block:: python + + class HelloConan(ConanFile): + ... + options = {"static": [True, False]} + default_options = "static=True" + + def build(self): + static = "-DBUILD_SHARED_LIBS=ON" if not self.options.static else "" + cmake = CMake(self.settings) + self.run("cmake . %s %s" % (cmake.command_line, static)) + self.run("cmake --build . %s" % cmake.build_config) + +Note that you have to consider the option properly in your build. In this case, we are using +the CMake way. You must also remove the **STATIC** linkage in the **CMakeLists.txt** file, +and if you are using VS, you also need to change your code to correctly import/export symbols +for the dll. + +You can use the ``ANY`` string to allow any value for a specified option. The range of values for +such an option will not be checked, and any value (as string) will be accepted. + +.. code-block:: python + + class HelloConan(ConanFile): + ... + options = {"commit": "ANY"} + default_options = "commit=1234abcd" + +This could be useful, for example, if you want to have an option so a package can actually reference any specific +commit of a git repository. + +You can also specify options of the package dependencies: + +.. code-block:: python + + class HelloConan(ConanFile): + requires = "Pkg/0.1@user/channel" + default_options = "Pkg:pkg_option=value" + +If you need to dynamically set some dependency options, you could do: + +.. code-block:: python + + class HelloConan(ConanFile): + requires = "Pkg/0.1@user/channel" + + def configure(self): + self.options["Pkg"].pkg_option = "value" + +requires +--------- + +Specify package dependencies as a list of other packages: + + +.. code-block:: python + + class MyLibConan(ConanFile): + requires = "Hello/1.0@user/stable", "OtherLib/2.1@otheruser/testing" + +You can specify further information about the package requirements: + +.. code-block:: python + + class MyLibConan(ConanFile): + requires = (("Hello/0.1@user/testing"), + ("Say/0.2@dummy/stable", "override"), + ("Bye/2.1@coder/beta", "private")) + +Requirements can be complemented by 2 different parameters: + +**private**: a dependency can be declared as private if it is going to be fully embedded and hidden +from consumers of the package. Typical examples could be a header only library which is not exposed +through the public interface of the package, or the linking of a static library inside a dynamic +one, in which the functionality or the objects of the linked static library are not exposed through +the public interface of the dynamic library. + +**override**: packages can define overrides of their dependencies, if they require the definition of +specific versions of the upstream required libraries, but not necessarily direct dependencies. For example, +a package can depend on A(v1.0), which in turn could conditionally depend on Zlib(v2), depending on whether +the compression is enabled or not. Now, if you want to force the usage of Zlib(v3) you can: + +.. code-block:: python + + class HelloConan(ConanFile): + requires = ("A/1.0@user/stable", ("Zlib/3.0@other/beta", "override")) + + +This **will not introduce a new dependency**, it will just change Zlib v2 to v3 if A actually +requires it. Otherwise Zlib will not be a dependency of your package. + +.. _version_ranges: + +version ranges +++++++++++++++ + +From conan 0.16, version ranges expressions are supported, both in ``conanfile.txt`` and in +``conanfile.py`` requirements. The syntax is using brackets: + +.. code-block:: python + + class HelloConan(ConanFile): + requires = "Pkg/[>1.0,<1.8]@user/stable" + +Expressions are those defined and implemented by [python node-semver](https://pypi.python.org/pypi/node-semver), +but using a comma instead of spaces. Accepted expressions would be: + +.. code-block:: python + + >1.1,<2.1 # In such range + 2.8 # equivalent to =2.8 + ~=3.0 # compatible, according to semver + >1.1 || 0.8 # conditions can be OR'ed + +Version ranges expressions are evaluated at the time of building the dependencies graph, from +downstream to upstream dependencies. No joint-compatibility of the full graph is computed, instead, +version ranges are evaluated when dependencies are first retrieved. + +This means, that if a package A, depends on another package B (A->B), and A has a requirement for +``C/[>1.2,<1.8]``, this requirements is evaluated first and it can lead to get the version ``C/1.7``. If +package B has the requirement to ``C/[>1.3,<1.6]``, this one will be overwritten by the downstream one, +it will output a version incompatibility error. But the "joint" compatibility of the graph will not +be obtained. Downstream packages or consumer projects can impose their own requirements to comply +with upstream constraints, in this case a override dependency to ``C/[>1.3,<1.6]`` can be easily defined +in the downstream package or project. + +The order of search for matching versions is as follows: + +- First, the local conan storage is searched for matching versions, unless the ``--update`` flag + is provided to ``conan install`` +- If a matching version is found, it is used in the dependency graph as a solution +- If no matching version is locally found, it starts to search in the remotes, in order. If some + remote is specified with ``-r=remote``, then only that remote will be used. +- If the ``--update`` parameter is used, then the existing packages in the local conan cache will + not be used, and the same search of the previous steps is carried out in the remotes. If new + matching versions are found, they will be retrieved, so subsequents call to ``install`` will + find them locally and use them. + + +exports +-------- +If a package recipe ``conanfile.py`` requires other external files, like other python files that +it is importing (python importing), or maybe some text file with data it is reading, those files +must be exported with the ``exports`` field, so they are stored together, side by side with the +``conanfile.py`` recipe. + +The ``exports`` field can be one single pattern, like ``exports="*"``, or several inclusion patterns. +For example, if we have some python code that we want the recipe to use in a ``helpers.py`` file, +and have some text file, ``info.txt``, we want to read and display during the recipe evaluation +we would do something like: + +.. code-block:: python + + exports = "helpers.py", "info.txt" + +This is an optional attribute, only to be used if the package recipe requires these other files +for evaluation of the recipe. + +exports_sources +---------------- +There are 2 ways of getting source code to build a package. Using the ``source()`` recipe method +and using the ``exports_sources`` field. With ``exports_sources`` you specify which sources are required, +and they will be exported together with the **conanfile.py**, copying them from your folder to the +local conan cache. Using ``exports_sources`` +the package recipe can be self-contained, containing the source code like in a snapshot, and then +not requiring downloading or retrieving the source code from other origins (git, download) with the +``source()`` method when it is necessary to build from sources. + +The ``exports_sources`` field can be one single pattern, like ``exports_sources="*"``, or several inclusion patterns. +For example, if we have the source code inside "include" and "src" folders, and there are other folders +that are not necessary for the package recipe, we could do: + +.. code-block:: python + + exports_sources = "include*", "src*" + +This is an optional attribute, used typically when ``source()`` is not specify. The main difference with +``exports`` is that ``exports`` files are always retrieved (even if pre-compiled packages exist), +while ``exports_sources`` files are only retrieved when it is necessary to build a package from sources. + +generators +---------- + +Generators specify which is the output of the ``install`` command in your project folder. By +default, a ``conanbuildinfo.txt`` file is generated, but you can specify different generators. + +Check the full generators list in :ref:`Reference/Generators` + +You can specify more than one generator: + +.. code-block:: python + + class MyLibConan(ConanFile): + generators = "cmake", "gcc" + + +build_policy +------------ + +With the ``build_policy`` attribute the package creator can change the default conan's build behavior. +The allowed ``build_policy`` values are: + +- ``missing``: If no binary package is found, conan will build it without the need of invoke conan install with **--build missing** option. +- ``always``: The package will be built always, **retrieving each time the source code** executing the "source" method. + + +.. code-block:: python + :emphasize-lines: 2 + + class PocoTimerConan(ConanFile): + build_policy = "always" # "missing" + +short_paths +------------ + +If one of the packages you are creating hits the limit of 260 chars path length in Windows, add +``short_paths=True`` in your conanfile.py: + +.. code-block:: python + + from conans import ConanFile + + class ConanFileTest(ConanFile): + ... + short_paths = True + +This will automatically "link" the ``source`` and ``build`` directories of the package to the drive root, +something like `C:/.conan/tmpdir`. All the folder layout in the conan cache is maintained. + +This attribute will not have any effect in other OS, it will be discarded. + +From Windows 10 (ver. 10.0.14393), it is possible to opt-in disabling the path limits. Check `this link +`_ for more info. Latest python installers might offer to enable this while installing python. With this limit removed, the ``short_paths`` functionality is totally unnecessary. + + +conanfile_directory +------------------- + +``self.conanfile_directory`` is a **read only property** that returns the directory in which the conanfile is +located. \ No newline at end of file diff --git a/reference/conanfile/methods.rst b/reference/conanfile/methods.rst new file mode 100644 index 000000000000..de4a93962b5f --- /dev/null +++ b/reference/conanfile/methods.rst @@ -0,0 +1,448 @@ +Methods +======= + + +.. _retrieve_source: + +source() +-------- + +The other way is to let conan retrieve the source code from any other external origin, github, or +just a regular download. This can be done in the ``source()`` method. + +For example, in the previous section, we "exported" the source code files, together with the **conanfile.py** file, +which can be handy if the source code is not under version control. But if the source code is available in a repository, +you can directly get it from there: + +.. code-block:: python + + from conans import ConanFile + + class HelloConan(ConanFile): + name = "Hello" + version = "0.1" + settings = "os", "compiler", "build_type", "arch" + + def source(self): + self.run("git clone https://github.com/memsharded/hello.git") + # You can also change branch, commit or whatever + # self.run("cd hello && git checkout 2fe5...") + + +This will work, as long as ``git`` is in your current path (so in Win you probably want to run things in msysgit, cmder, etc). +You can also use another VCS or direct download/unzip. For that purpose, we have provided some helpers, +but you can use your own code or origin as well. This is a snippet of the conanfile of the POCO libray: + + +.. code-block:: python + + from conans import ConanFile + from conans.tools import download, unzip, check_md5, check_sha1, check_sha256 + import os + import shutil + + class PocoConan(ConanFile): + name = "Poco" + version = "1.6.0" + + def source(self): + zip_name = "poco-1.6.0-release.zip" + download("https://github.com/pocoproject/poco/archive/poco-1.6.0-release.zip", zip_name) + # check_md5(zip_name, "51e11f2c02a36689d6ed655b6fff9ec9") + # check_sha1(zip_name, "8d87812ce591ced8ce3a022beec1df1c8b2fac87") + # check_sha256(zip_name, "653f983c30974d292de58444626884bee84a2731989ff5a336b93a0fef168d79") + unzip(zip_name) + shutil.move("poco-poco-1.6.0-release", "poco") + os.unlink(zip_name) + +The download, unzip utilities can be imported from conan, but you can also use your own code here +to retrieve source code from any origin. You can even create packages for pre-compiled libraries +you already have, even if you don't have the source code. You can download the binaries, skip +the ``build()`` method and define your ``package()`` and ``package_info()`` accordingly. + +You can also use **check_md5**, **check_sha1** and **check_sha256** from the **tools** module to verify that a package is downloaded correctly. + +build() +-------- + +Build helpers ++++++++++++++ + +You can use these classes to prepare your build system's command invocation: + +- **CMake**: Prepares the invocation of cmake command with your settings. +- **AutoToolsBuildEnvironment**: If you are using configure/Makefile to build your project you can use this helper. + Read more: :ref:`Building with Autotools `. +- **VisualStudioBuildEnvironment**: If you are calling your Visual Studio compiler directly to build your project you can use this helper. + Read more: :ref:`Building with Visual Studio `. +- **tools.build_sln_command()**: If you have an ``sln`` project you can use this tool to build it. + Read more: :ref:`Build an existing Visual Studio project `. +- **GCC generator**: If you are calling GCC or Clang directly to build your project you can use the ``gcc`` generator. + Read more: :ref:`Building with GCC or Clang `. + + + +(Unit) Testing your library +++++++++++++++++++++++++++++ +We have seen how to run package tests with conan, but what if we want to run full unit tests on +our library before packaging, so that they are run for every build configuration? +Nothing special is required here. We can just launch the tests from the last command in our +``build()`` method: + +.. code-block:: python + + def build(self): + cmake = CMake(self.settings) + self.run("cmake . %s %s" % (cmake.command_line)) + self.run("cmake --build . %s" % cmake.build_config) + # here you can run CTest, launch your binaries, etc + self.run("ctest") + + +package() +--------- +The actual creation of the package, once that it is build, is done in the ``package()`` method. +Using the ``self.copy()`` method, artifacts are copied from the build folder to the package folder. +The syntax of copy is as follows: + +.. code-block:: python + + self.copy(pattern, dst, src, keep_path=False) + + +- ``pattern`` is a pattern following fnmatch syntax of the files you want to copy, from the *build* to the *package* folders. Typically something like ``*.lib`` or ``*.h`` +- ``dst`` is the destination folder in the package. They will typically be ``include`` for headers, ``lib`` for libraries and so on, though you can use any convention you like +- ``src`` is the folder where you want to search the files in the *build* folder. If you know that your libraries when you build your package will be in *build/lib*, you will typically use ``build/lib`` in this parameter. Leaving it empty means the root build folder. +- ``keep_path``, with default value=True, means if you want to keep the relative path when you copy the files from the source(build) to the destination(package). Typically headers, you keep the relative path, so if the header is in *build/include/mylib/path/header.h*, you write: +- ``links``, with default value=False, you can activate it to copy symlinks, like typical lib.so->lib.so.9 + + +.. code-block:: python + + self.copy("*.h", "include", "build/include") #keep_path default is True + +so the final path in the package will be: ``include/mylib/path/header.h``, and as the *include* is usually added to the path, the includes will be in the form: ``#include "mylib/path/header.h"`` which is something desired + +``keep_path=False`` is something typically desired for libraries, both static and dynamic. Some compilers as MSVC, put them in paths as *Debug/x64/MyLib/Mylib.lib*. Using this option, we could write: + +.. code-block:: python + + self.copy("*.lib", "lib", "", keep_path=False) + + +And it will copy the lib to the package folder *lib/Mylib.lib*, which can be linked easily + +.. note:: + + If you are using CMake and you have an install target defined in your CMakeLists.txt, you + might be able to reuse it for this ``package()`` method. Please check :ref:`reuse_cmake_install` + + +.. _package_info: + +package_info() +--------------- + +cpp_info ++++++++++ +Each package has to specify certain build information for its consumers. This can be done in +the ``cpp_info`` attribute within the ``package_info()`` method. + +The ``cpp_info`` attribute has the following properties you can assign/append to: + +.. code-block:: python + + self.cpp_info.includedirs = ['include'] # Ordered list of include paths + self.cpp_info.libs = [] # The libs to link against + self.cpp_info.libdirs = ['lib'] # Directories where libraries can be found + self.cpp_info.resdirs = ['res'] # Directories where resources, data, etc can be found + self.cpp_info.bindirs = [] # Directories where executables and shared libs can be found + self.cpp_info.defines = [] # preprocessor definitions + self.cpp_info.cflags = [] # pure C flags + self.cpp_info.cppflags = [] # C++ compilation flags + self.cpp_info.sharedlinkflags = [] # linker flags + self.cpp_info.exelinkflags = [] # linker flags + + +* includedirs: list of relative paths (starting from the package root) of directories where headers + can be found. By default it is initialized to ['include'], and it is rarely changed. +* libs: ordered list of libs the client should link against. Empty by default, it is common + that different configurations produce different library names. For example: + +.. code-block:: python + + def package_info(self): + if not self.settings.os == "Windows": + self.cpp_info.libs = ["libzmq-static.a"] if self.options.static else ["libzmq.so"] + else: + ... + +* libdirs: list of relative paths (starting from the package root) of directories in which to find + library object binaries (.lib, .a, .so. dylib). By default it is initialize to ['lib'], and it is rarely changed. +* resdirs: list of relative paths (starting from the package root) of directories in which to find + resource files (images, xml, etc). By default it is initialize to ['res'], and it is rarely changed. +* bindirs: list of relative paths (starting from the package root) of directories in which to find + library runtime binaries (like windows .dlls). By default it is initialized to ['bin'], and it is rarely changed. +* defines: ordered list of preprocessor directives. It is common that the consumers have to specify + some sort of defines in some cases, so that including the library headers matches the binaries: +* flags, list of flags that the consumer should activate for proper + behavior. Usage of C++11 could be configured here, for example, although it is true that the consumer may + want to do some flag processing to check if different dependencies are setting incompatible flags + (c++11 after c++14) + +.. code-block:: python + + if self.options.static: + if self.settings.compiler == "Visual Studio": + self.cpp_info.libs.append("ws2_32") + self.cpp_info.defines = ["ZMQ_STATIC"] + + if not self.settings.os == "Windows": + self.cpp_info.cppflags = ["-pthread"] + + +.. _environment_information: + +env_info ++++++++++ + +Each package can also define some environment variables that the package needs to be reused. +It's specially useful for :ref:`installer packages`, to set the path with the "bin" folder of the packaged application. +This can be done in the ``env_info`` attribute within the ``package_info()`` method. + +.. code-block:: python + + self.env_info.path.append("ANOTHER VALUE") # Append "ANOTHER VALUE" to the path variable + self.env_info.othervar = "OTHER VALUE" # Assign "OTHER VALUE" to the othervar variable + self.env_info.thirdvar.append("some value") # Every variable can be set or appended a new value + + +The :ref:`virtualenv` generator will use the self.env_info variables to prepare a script to activate/deactive a virtual environment. + +In previous conan versions you needed to use `ConfigureEnvironment` helper (now deprecated) to reuse these variables, but it's not needed anymore. +They will be automatically applied before calling the consumer conanfile.py methods `source`, `build`, `package` and `imports`. + + +.. _configure_config_options: + +configure(), config_options() +----------------------------- + +Note: ``config()`` method has been deprecated, used ``configure()`` instead. + +If the package options and settings are related, and you want to configure either, you can do so +in the ``configure()`` and ``config_options()`` methods. This is an example: + +.. code-block:: python + + class MyLibConan(ConanFile): + name = "MyLib" + version = "2.5" + settings = "os", "compiler", "build_type", "arch" + options = {"static": [True, False], + "header_only": [True False]} + + def config(self): + # If header only, the compiler, etc, does not affect the package! + if self.options.header_only: + self.settings.clear() + self.options.remove("static") + +The package has 2 options set, to be compiled as a static (as opposed to shared) library, +and also not to involve any builds, because header-only libraries will be used. In this case, +the settings that would affect a normal build, and even the other option (static vs shared) +do not make sense, so we just clear them. That means, if someone consumes MyLib with the +``header_only: True`` option, the package downloaded and used will be the same, irrespective of +the OS, compiler or architecture the consumer is building with. + +The most typical usage would be the one with ``configure()`` while ``config_options()`` should be +used more sparingly. ``config_options()`` is used to configure or constraint the available +options in a package, **before** they are given a value. So when a value is tried to be assigned, +it will raise an error. For example, let's suppose that a certain package library cannot be +built as shared library in Windows, it can be done: + +.. code-block:: python + + def config_options(self): + if self.settings.os == "Windows": + del self.options.shared + +This will be executed before the actual assignment of ``options`` (then, such ``options`` values +cannot be used inside this function), so the command ``$ conan install -o Pkg:shared=True`` will +raise an Exception in Windows saying that ``shared`` is not an option for such package. + + +requirements() +-------------- + +Besides the ``requires`` field, more advanced requirement logic can be defined in the +``requirements()`` optional method, using for example values from the package ``settings`` or +``options``: + + +.. code-block:: python + + def requirements(self): + if self.options.myoption: + self.requires("zlib/1.2@drl/testing") + else: + self.requires("opencv/2.2@drl/stable") + +This is a powerful mechanism for handling **conditional dependencies**. + +When you are inside the method, each call to ``self.requires()`` will add the corresponding +requirement to the current list of requirements. It also has optional parameters that allow +defining the special cases, as is shown below: + +.. code-block:: python + + def requirements(self): + self.requires("zlib/1.2@drl/testing", private=True, override=False) + +.. _system_requirements: + +system_requirements() +---------------------- +It is possible to install system-wide packages from conan. Just add a ``system_requirements()`` +method to your conanfile and specify what you need there. + +You can use ``conans.tools.os_info`` object to detect the operating system, version and distribution (linux): + +- ``os_info.is_linux`` True if Linux +- ``os_info.is_windows`` True if Windows +- ``os_info.is_macos`` True if OSx +- ``os_info.os_version`` OS version +- ``os_info.os_version_name`` Common name of the OS (Windows 7, Mountain Lion, Wheezy...) +- ``os_info.linux_distro`` Linux distribution name (None if not Linux) + +Also you can use ``SystemPackageTool`` class, that will automatically invoke the right system package tool: **apt**, **yum** or **brew** depending on the system we are running. + +.. code-block:: python + + from conans.tools import os_info, SystemPackageTool + + def system_requirements(self): + pack_name = None + if os_info.linux_distro == "ubuntu": + if os_info.os_version > "12": + pack_name = "package_name_in_ubuntu_10" + else: + pack_name = "package_name_in_ubuntu_12" + elif os_info.linux_distro == "fedora" or os_info.linux_distro == "centos": + pack_name = "package_name_in_fedora_and_centos" + elif os_info.is_macos: + pack_name = "package_name_in_macos" + + if pack_name: + installer = SystemPackageTool() + installer.install(pack_name) # Install the package, will update the package database if pack_name isn't already installed + + +SystemPackageTool methods: + +- **update()**: Updates the system package manager database. It's called automatically from the ``install()`` method by default. +- **install(packages, update=True, force=False)**: Installs the ``packages`` (could be a list or a string). If ``update`` is True it will + execute ``update()`` first if it's needed. The packages won't be installed if they are already installed at least of ``force`` + parameter is set to True. If ``packages`` is a list the first available package will be picked (short-circuit like logical **or**). + + +The use of ``sudo`` in the internals of the ``install()`` and ``update()`` methods is controlled by the CONAN_SYSREQUIRES_SUDO +environment variable, so if the users don't need sudo permissions, it is easy to opt-in/out. + +Conan will keep track of the execution of this method, so that it is not invoked again and again +at every conan command. The execution is done per package, since some packages of the same +library might have different system dependencies. If you are sure that all your binary packages +have the same system requirements, just add the following line to your method: + +.. code-block:: python + + def system_requirements(self): + self.global_system_requirements=True + if ... + + + +imports() +--------------- +Importing files copies files from the local store to your project. This feature is handy +for copying shared libraries (dylib in Mac, dll in Win) to the directory of your executable, so that you don't have +to mess with your PATH to run them. But there are other use cases: + +- Copy an executable to your project, so that it can be easily run. A good example is the google + **protobuf** code generator, go to the examples section to check it out. +- Copy package data to your project, like configuration, images, sounds... A good example is the + OpenCV demo, in which face detection XML pattern files are required. + +Importing files is also very convenient in order to redistribute your application, as many times +you will just have to bundle your project's bin folder. + +A typical ``imports()`` method for shared libs could be: + +.. code-block:: python + + def imports(self): + self.copy("*.dll", "", "bin") + self.copy("*.dylib", "", "lib") + +conan_info() +------------ + +Deprecated, use ``package_id()`` method instead. + + +package_id() +------------ + +Conan keeps the compatibility between binary packages using ``settings``. +When a recipe author specifies some settings in the :ref:`settings_property` property, is telling that any change at any +of those settings will require a different binary package. + +But sometimes you would need to alter the general behavior, for example, to have only one binary package for several different compiler versions. + +Please, check the section :ref:`how_to_define_abi_compatibility` to get more details. + +.. _build_id: + +build_id() +------------ + +In the general case, there is one build folder for each binary package, with the exact same hash/ID +of the package. However this behavior can be changed, there are a couple of scenarios that this might +be interesting: + +- You have a build script that generates several different configurations at once, like both debug + and release artifacts, but you actually want to package and consume them separately. Same for + different architectures or any other setting +- You build just one configuration (like release), but you want to create different binary packages + for different consuming cases. For example, if you have created tests for the library in the build + step, you might want to create to package, one just containing the library for general usage, but + another one also containing the tests, as a reference and a tool to debug errors. + +In both cases, if using different settings, the system will build twice (or more times) the same binaries, +just to produce a different final binary package. With the ``build_id()`` method this logic can be +changed. ``build_id()`` will create a new package ID/hash for the build folder, and you can define +the logic you want in it, for example: + +.. code-block:: python + + settings = "os", "compiler", "arch", "build_type" + + def build_id(self): + self.info_build.settings.build_type = "Any" + + +So this recipe will generate a final different package for each debug/release configuration. But +as the ``build_id()`` will generate the same ID for any ``build_type``, then just one folder and +one build will be done. Such build should build both debug and release artifacts, and then the +``package()`` method should package them accordingly to the ``self.settings.build_type`` value. +Still different builds will be executed if using different compilers or architectures. This method +is basically an optimization of build time, avoiding multiple re-builds. + +Other information as custom package options can also be changed: + +.. code-block:: python + + def build_id(self): + self.info_build.options.myoption = 'MyValue' # any value possible + self.info_build.options.fullsource = 'Always' + diff --git a/reference/conanfile/other.rst b/reference/conanfile/other.rst new file mode 100644 index 000000000000..66f5c514555b --- /dev/null +++ b/reference/conanfile/other.rst @@ -0,0 +1,32 @@ +Output and Running +================== + +Output contents +--------------- + +Use the `self.output` to print contents to the output. + +.. code-block:: python + + self.output.success("This is a good, should be green") + self.output.info("This is a neutral, should be white") + self.output.warn("This is a warning, should be yellow") + self.output.error("Error, should be red") + self.output.rewrite_line("for progress bars, issues a cr") + +Check the source code. You might be able to produce different outputs with different colors. + + +Running commands +---------------- + +``self.run()`` is a helper to run system commands and throw exceptions when errors occur, +so that command errors are do not pass unnoticed. It is just a wrapper for ``os.system()`` + +Optional parameters: + +- ``output``: Defaulted to True, will write in stdout. You can pass any stream that accepts a ``write`` method like a ``StringIO.StringIO()`` + Note: Be careful with the Python2 and Python3 compatibility, StringIO has been realocated between them. + +- ``cwd``: Current directory to run the command. Default "." + diff --git a/reference/conanfile_txt.rst b/reference/conanfile_txt.rst new file mode 100644 index 000000000000..05c87b09b3eb --- /dev/null +++ b/reference/conanfile_txt.rst @@ -0,0 +1,7 @@ +.. _conanfile_txt_reference: + +conanfile.txt +============= + + +!! PENDING \ No newline at end of file diff --git a/reference/config_files.rst b/reference/config_files.rst index 7b11c8d95beb..fc864e3128c3 100644 --- a/reference/config_files.rst +++ b/reference/config_files.rst @@ -13,5 +13,4 @@ These are the most important configuration files, used to customize conan. config_files/settings.yml config_files/registry.txt config_files/short_paths.conf - config_files/profiles config_files/artifacts.properties diff --git a/reference/config_files/profiles.rst b/reference/config_files/profiles.rst deleted file mode 100644 index 82eef89ba5e5..000000000000 --- a/reference/config_files/profiles.rst +++ /dev/null @@ -1,109 +0,0 @@ -.. _profiles: - -Profiles -======== - -A profile text file has to be located in ``.conan/profiles/`` directory. -It's a text file that contains a predefined set of ``settings``, ``options``, ``environment variables``` and ``scopes`` and has this structure: - -.. code-block:: text - - [settings] - setting=value - - [options] - MyLib:shared=True - - [env] - env_var=value - - [scopes] - scope=value - - -Profiles are useful for change global settings without specifying multiple "-s" and "-o"parameters in ``conan install`` or ``conan test`` command. - -For example, if you are working with Linux and you usually work with ``gcc`` compiler, but you have installed ``clang`` -compiler and want to install some package for ``clang`` compiler, you could do: - -- Create a ``.conan/profiles/clang`` file: - -.. code-block:: text - - [settings] - compiler=clang - compiler.version=3.5 - compiler.libcxx=libstdc++11 - - [env] - CC=/usr/bin/clang - CXX=/usr/bin/clang++ - - -- Execute conan install command passing the ``--profile`` or ``-pr`` parameter: - - -.. code-block:: bash - - conan install --profile clang - - - -Without profiles you would have needed to set the CC and CXX variables in the environment to point to your clang compiler and use ``-s`` parameters to specify the settings: - - -.. code-block:: bash - - export CC=/usr/bin/clang - export CXX=/usr/bin/clang++ - conan install -s compiler=clang -s compiler.version=3.5 -s compiler.libcxx=libstdc++11 - - -A profile can also be used in ``conan test_package`` and ``info`` command: - -.. code-block:: bash - - $ conan test_package --profile clang - - -Profiles can be located in different folders, and be referenced by absolute or relative path: - -.. code-block:: bash - - $ conan install --profile /abs/path/to/profile # abs path - $ conan install --profile ./relpath/to/profile # resolved to current dir - $ conan install --profile profile # resolved to user/.conan/profiles/profile - -You can use ``$PROFILE_DIR`` in your profile and it will be replaced with the absolute path to the profile file. -It is useful to declare relative folders: - -.. code-block:: text - - [env] - PYTHONPATH=$PROFILE_DIR/my_python_tools - - -Package settings and env vars -............................. - -Profiles also support **package settings** and **package environment variables** definition, so you can override some settings or env vars for some specific package: - - -- Create a ``.conan/profiles/zlib_with_clang`` file: - -.. code-block:: text - - [settings] - zlib:compiler=clang - zlib:compiler.version=3.5 - zlib:compiler.libcxx=libstdc++11 - compiler=gcc - compiler.version=4.9 - compiler.libcxx=libstdc++11 - - [env] - zlib:CC=/usr/bin/clang - zlib:CXX=/usr/bin/clang++ - -- Your build tool will locate **clang** compiler only for the **zlib** package and **gcc** (default one) for the rest of your dependency tree. - diff --git a/reference/generators.rst b/reference/generators.rst new file mode 100644 index 000000000000..17eeedd50356 --- /dev/null +++ b/reference/generators.rst @@ -0,0 +1,27 @@ +.. _generators_reference: + +Generators +========== + +You can specify a generator in: + +- The **[generators]** section from :ref:`conanfile.txt` +- The **generators** attribute in :ref:`conanfile.py` + +Available generators: + +.. toctree:: + :maxdepth: 1 + + generators/cmake + generators/cmakemulti + generators/visualstudio + generators/xcode + generators/gcc + generators/qbs + generators/qmake + generators/scons + generators/virtualenv + generators/virtualbuildenv + generators/virtualrunenv + generators/ycm diff --git a/reference/generators/cmake.rst b/reference/generators/cmake.rst new file mode 100644 index 000000000000..4ac6aa22f539 --- /dev/null +++ b/reference/generators/cmake.rst @@ -0,0 +1,121 @@ +.. _cmake_generator: + + +`cmake` +======= + +.. container:: out_reference_box + + This is the reference page for ``cmake`` generator. + Go to :ref:`Integrations/CMake` if you want to learn how to integrate your project or recipes with CMake. + + +It generates a file named ``conanbuildinfo.cmake`` and declares some variables and methods + +.. _conanbuildinfocmake_variables: + +Variables in conanbuildinfo.cmake +--------------------------------- + +- **Package declared vars** + +For each requirement ``conanbuildinfo.cmake`` file declares the following variables. +``XXX`` is the name of the require in uppercase. e.k "ZLIB" for ``zlib/1.2.8@lasote/stable`` requirement: + ++--------------------------------+----------------------------------------------------------------------+ +| NAME | VALUE | ++================================+======================================================================+ +| CONAN_XXX_ROOT | Abs path to root package folder. | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_INCLUDE_DIRS_XXX | Header's folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIB_DIRS_XXX | Library folders (default {CONAN_XXX_ROOT}/lib) | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_BIN_DIRS_XXX | Binary folders (default {CONAN_XXX_ROOT}/bin) | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIBS_XXX | Library names to link | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_DEFINES_XXX | Library defines | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_COMPILE_DEFINITIONS_XXX | Compile definitions | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_CXX_FLAGS_XXX | CXX flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_SHARED_LINK_FLAGS_XXX | Shared link flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_C_FLAGS_XXX | C flags | ++--------------------------------+----------------------------------------------------------------------+ + + +- **Global declared vars** + +Conan also declares some global variables with the aggregated values of all our requirements. +The values are ordered in the right order according to the dependency tree. + ++--------------------------------+----------------------------------------------------------------------+ +| NAME | VALUE | ++================================+======================================================================+ +| CONAN_INCLUDE_DIRS | Aggregated header's folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIB_DIRS | Aggregated library folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_BIN_DIRS | Aggregated binary folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIBS | Aggregated library names to link | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_DEFINES | Aggregated library defines | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_COMPILE_DEFINITIONS | Aggregated compile definitions | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_CXX_FLAGS | Aggregated CXX flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_SHARED_LINK_FLAGS | Aggregated Shared link flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_C_FLAGS | Aggregated C flags | ++--------------------------------+----------------------------------------------------------------------+ + + +.. _conanbuildinfocmake_methods: + +Methods available in conanbuildinfo.cmake +----------------------------------------- + ++--------------------------------+-------------------------------------------------------------------------------------------+ +| NAME | DESCRIPTION | ++================================+===========================================================================================+ +| conan_basic_setup() | Setup all the CMake vars according to our settings with the global approach (no targets) | ++--------------------------------+-------------------------------------------------------------------------------------------+ +| conan_basic_setup(TARGETS) | Setup all the CMake vars by target (only CMake > 3.1.2) | ++--------------------------------+-------------------------------------------------------------------------------------------+ +| conan_target_link_libraries() | Helper to link all libraries to a specified target | ++--------------------------------+-------------------------------------------------------------------------------------------+ + + + +Other optional methods +---------------------- + +There are other methods automatically called by ``conan_basic_setup()`` but you can use them directly: + ++--------------------------------+----------------------------------------------------------------------+ +| NAME | DESCRIPTION | ++================================+======================================================================+ +| conan_check_compiler() | Checks that your compiler matches with the declared in the settings | ++--------------------------------+----------------------------------------------------------------------+ +| conan_output_dirs_setup() | Adjust the bin/ and lib/ output directories | ++--------------------------------+----------------------------------------------------------------------+ +| conan_set_find_library_paths() | Set CMAKE_INCLUDE_PATH and CMAKE_INCLUDE_PATH | ++--------------------------------+----------------------------------------------------------------------+ +| conan_global_flags() | Set include_directories, link_directories, link_directories, flags | ++--------------------------------+----------------------------------------------------------------------+ +| conan_define_targets() | Define the targets (target flags instead of global flags) | ++--------------------------------+----------------------------------------------------------------------+ +| conan_set_rpath() | Set CMAKE_SKIP_RPATH=1 if APPLE | ++--------------------------------+----------------------------------------------------------------------+ +| conan_set_vs_runtime() | Adjust the runtime flags (/MD /MDd /MT /MTd) | ++--------------------------------+----------------------------------------------------------------------+ +| conan_set_libcxx(TARGETS) | Adjust the standard library flags (libstdc++, libc++, libstdc++11) | ++--------------------------------+----------------------------------------------------------------------+ +| conan_set_find_paths() | Adjust CMAKE_MODULE_PATH and CMAKE_PREFIX_PATH | ++--------------------------------+----------------------------------------------------------------------+ + diff --git a/reference/generators/cmakemulti.rst b/reference/generators/cmakemulti.rst new file mode 100644 index 000000000000..5d60dc9926e6 --- /dev/null +++ b/reference/generators/cmakemulti.rst @@ -0,0 +1,41 @@ +.. _cmakemulti_generator: + + +`cmakemulti` +============ + +.. container:: out_reference_box + + This is the reference page for ``cmakemulti`` generator. + Go to :ref:`Integrations/CMake` if you want to learn how to integrate your project or recipes with CMake. + +Usage +----- + +.. code-block:: bash + + $ conan install -g cmake_multi -s build_type=Release -s compiler.runtime=MD ... + $ conan install -g cmake_multi -s build_type=Debug -s compiler.runtime=MDd ... + +These commands will generate 3 files: + +- ``conanbuildinfo_release.cmake``: Variables adjusted only for build_type Release +- ``conanbuildinfo_debug.cmake``: Variables adjusted only for build_type Debug +- ``conanbuildinfo_multi.cmake``: Which includes the other two, and enables its use + +Variables in conanbuildinfo_release.cmake +----------------------------------------- + +Same as :ref:`conanbuildinfo.cmake` with suffix ``_RELEASE`` + + +Variables in conanbuildinfo_debug.cmake +--------------------------------------- + +Same as :ref:`conanbuildinfo.cmake` with suffix ``_DEBUG`` + + +Available Methods +----------------- + +Same as :ref:`conanbuildinfo.cmake` diff --git a/reference/generators/gcc.rst b/reference/generators/gcc.rst new file mode 100644 index 000000000000..6dc00ce6c938 --- /dev/null +++ b/reference/generators/gcc.rst @@ -0,0 +1,50 @@ + +.. _gcc_generator: + +gcc +=== + +.. container:: out_reference_box + + This is the reference page for ``gcc`` generator. + Go to :ref:`Integrations/GCC / Clang` if you want to learn how to integrate your project or recipes with ``gcc`` or ``clang`` +compilers. + + + +Generates a file named ``conanbuildinfo.gcc`` containing a command line parameters to invoke ``gcc`` or ``clang`` +compilers. + +.. code-block:: bash + + > g++ timer.cpp @conanbuildinfo.gcc -o bin/timer + ++--------------------------------+----------------------------------------------------------------------+ +| OPTION | VALUE | ++================================+======================================================================+ +| -DXXX | Corresponding to requirements `defines` | ++--------------------------------+----------------------------------------------------------------------+ +| -IXXX | Corresponding to requirements `include dirs` | ++--------------------------------+----------------------------------------------------------------------+ +| -Wl,-rpathXXX | Corresponding to requirements `lib dirs` | ++--------------------------------+----------------------------------------------------------------------+ +| -LXXX | Corresponding to requirements `lib dirs` | ++--------------------------------+----------------------------------------------------------------------+ +| -lXXX | Corresponding to requirements `libs` | ++--------------------------------+----------------------------------------------------------------------+ +| -m64 | For x86_64 architecture | ++--------------------------------+----------------------------------------------------------------------+ +| -m32 | For x86 architecture | ++--------------------------------+----------------------------------------------------------------------+ +| -DNDEBUG | For Release builds | ++--------------------------------+----------------------------------------------------------------------+ +| -s | For Release builds (only gcc) | ++--------------------------------+----------------------------------------------------------------------+ +| -g | For Debug builds | ++--------------------------------+----------------------------------------------------------------------+ +| -D_GLIBCXX_USE_CXX11_ABI=0 | When setting libcxx == "libstdc++" | ++--------------------------------+----------------------------------------------------------------------+ +| -D_GLIBCXX_USE_CXX11_ABI=1 | When setting libcxx == "libstdc++11" | ++--------------------------------+----------------------------------------------------------------------+ +| Other flags | cppflags, cflags, sharedlinkflags, exelinkflags (applied directly) | ++--------------------------------+----------------------------------------------------------------------+ diff --git a/reference/generators/qbs.rst b/reference/generators/qbs.rst new file mode 100644 index 000000000000..394fc1f55374 --- /dev/null +++ b/reference/generators/qbs.rst @@ -0,0 +1,69 @@ +.. _qbs_generator: + +qbs +=== + +.. container:: out_reference_box + + This is the reference page for ``qbs`` generator. + Go to :ref:`Integrations/Qbs` if you want to learn how to integrate your project or recipes with Qbs. + + +Generates a file named ``conanbuildinfo.qbs`` that can be used for your qbs builds. + +A Product ``ConanBasicSetup`` contains the aggregated requirement values and also there is N Product declared, one per +requirement. + + +.. code-block:: json + + import qbs 1.0 + + Project { + Product { + name: "ConanBasicSetup" + Export { + Depends { name: "cpp" } + cpp.includePaths: [{INCLUDE DIRECTORIES REQUIRE 1}, {INCLUDE DIRECTORIES REQUIRE 2}] + cpp.libraryPaths: [{LIB DIRECTORIES REQUIRE 1}, {LIB DIRECTORIES REQUIRE 2}] + cpp.systemIncludePaths: [{BIN DIRECTORIES REQUIRE 1}, {BIN DIRECTORIES REQUIRE 2}] + cpp.dynamicLibraries: [{LIB NAMES REQUIRE 1}, {LIB NAMES REQUIRE 2}] + cpp.defines: [] + cpp.cppFlags: [] + cpp.cFlags: [] + cpp.linkerFlags: [] + } + } + + Product { + name: "REQUIRE1" + Export { + Depends { name: "cpp" } + cpp.includePaths: [{INCLUDE DIRECTORIES REQUIRE 1}] + cpp.libraryPaths: [{LIB DIRECTORIES REQUIRE 1}] + cpp.systemIncludePaths: [{BIN DIRECTORIES REQUIRE 1}] + cpp.dynamicLibraries: ["{LIB NAMES REQUIRE 1}"] + cpp.defines: [] + cpp.cppFlags: [] + cpp.cFlags: [] + cpp.linkerFlags: [] + } + } + // lib root path: {ROOT PATH REQUIRE 1} + + Product { + name: "REQUIRE2" + Export { + Depends { name: "cpp" } + cpp.includePaths: [{INCLUDE DIRECTORIES REQUIRE 2}] + cpp.libraryPaths: [{LIB DIRECTORIES REQUIRE 2}] + cpp.systemIncludePaths: [{BIN DIRECTORIES REQUIRE 2}] + cpp.dynamicLibraries: ["{LIB NAMES REQUIRE 2}"] + cpp.defines: [] + cpp.cppFlags: [] + cpp.cFlags: [] + cpp.linkerFlags: [] + } + } + // lib root path: {ROOT PATH REQUIRE 2} + } \ No newline at end of file diff --git a/reference/generators/qmake.rst b/reference/generators/qmake.rst new file mode 100644 index 000000000000..9c00725b101b --- /dev/null +++ b/reference/generators/qmake.rst @@ -0,0 +1,86 @@ +.. _qmake_generator: + +qmake +===== + +.. container:: out_reference_box + + This is the reference page for ``qmake`` generator. + Go to :ref:`Integrations/Qmake` if you want to learn how to integrate your project or recipes with qmake. + + +Generates a file named ``conanbuildinfo.pri`` that can be used for your qbs builds. +The file contains: + +- N groups of variables, one group per require, declaring the same individual values: include_paths, libs, bin dirs, libraries, defines etc. +- One group of global variables with the aggregated values for all requirements. + + +**Package declared vars** + +For each requirement ``conanbuildinfo.pri`` file declares the following variables. +``XXX`` is the name of the require in uppercase. e.k "ZLIB" for ``zlib/1.2.8@lasote/stable`` requirement: + ++--------------------------------+----------------------------------------------------------------------+ +| NAME | VALUE | ++================================+======================================================================+ +| CONAN_XXX_ROOT | Abs path to root package folder. | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_INCLUDEPATH_XXX | Header's folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIB_DIRS_XXX | Library folders (default {CONAN_XXX_ROOT}/lib) | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_BINDIRS_XXX | Binary folders (default {CONAN_XXX_ROOT}/bin) | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIBS_XXX | Library names to link | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_DEFINES_XXX | Library defines | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_COMPILE_DEFINITIONS_XXX | Compile definitions | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_QMAKE_CXXFLAGS_XXX | CXX flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_QMAKE_LFLAGS_XXX | Shared link flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_QMAKE_CFLAGS_XXX | C flags | ++--------------------------------+----------------------------------------------------------------------+ + + +**Global declared vars** + +Conan also declares some global variables with the aggregated values of all our requirements. +The values are ordered in the right order according to the dependency tree. + ++--------------------------------+----------------------------------------------------------------------+ +| NAME | VALUE | ++================================+======================================================================+ +| CONAN_INCLUDEPATH | Aggregated header's folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIB_DIRS | Aggregated library folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_BINDIRS | Aggregated binary folders | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_LIBS | Aggregated library names to link | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_DEFINES | Aggregated library defines | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_COMPILE_DEFINITIONS | Aggregated compile definitions | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_QMAKE_CXXFLAGS | Aggregated CXX flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_QMAKE_LFLAGS | Aggregated Shared link flags | ++--------------------------------+----------------------------------------------------------------------+ +| CONAN_QMAKE_CFLAGS | Aggregated C flags | ++--------------------------------+----------------------------------------------------------------------+ + + +.. _conanbuildinfoqmake_methods: + +Methods available in conanbuildinfo.pri +----------------------------------------- + ++--------------------------------+-------------------------------------------------------------------------------+ +| NAME | DESCRIPTION | ++================================+===============================================================================+ +| conan_basic_setup() | Setup all the qmake vars according to our settings with the global approach | ++--------------------------------+-------------------------------------------------------------------------------+ diff --git a/reference/generators/scons.rst b/reference/generators/scons.rst new file mode 100644 index 000000000000..0f5c25bc6eac --- /dev/null +++ b/reference/generators/scons.rst @@ -0,0 +1,6 @@ +.. _scons_generator: + +scons +===== + +!! PENDING \ No newline at end of file diff --git a/reference/generators/text.rst b/reference/generators/text.rst new file mode 100644 index 000000000000..5555cdfd4c8f --- /dev/null +++ b/reference/generators/text.rst @@ -0,0 +1,7 @@ +.. _text_generator: + +txt +=== + + +!! PENDING \ No newline at end of file diff --git a/reference/generators/virtualbuildenv.rst b/reference/generators/virtualbuildenv.rst new file mode 100644 index 000000000000..eaccb8f2ed3c --- /dev/null +++ b/reference/generators/virtualbuildenv.rst @@ -0,0 +1,4 @@ +.. _virtualbuildenv_generator: + +virtualbuildenv +=============== \ No newline at end of file diff --git a/reference/generators/virtualenv.rst b/reference/generators/virtualenv.rst new file mode 100644 index 000000000000..983f746cd78a --- /dev/null +++ b/reference/generators/virtualenv.rst @@ -0,0 +1,4 @@ +.. _virtualenv_generator: + +virtualenv +========= \ No newline at end of file diff --git a/reference/generators/virtualrunenv.rst b/reference/generators/virtualrunenv.rst new file mode 100644 index 000000000000..54e5411e54b6 --- /dev/null +++ b/reference/generators/virtualrunenv.rst @@ -0,0 +1,4 @@ +.. _virtualrunenv_generator: + +virtualrunenv +============= \ No newline at end of file diff --git a/reference/generators/visualstudio.rst b/reference/generators/visualstudio.rst new file mode 100644 index 000000000000..cfd56185e2c0 --- /dev/null +++ b/reference/generators/visualstudio.rst @@ -0,0 +1,46 @@ +.. _visualstudio_generator: + +visual_studio +============= + +.. container:: out_reference_box + + This is the reference page for ``visual_studio`` generator. + Go to :ref:`Integrations/Visual Studio` if you want to learn how to integrate your project or recipes with Visual Studio. + + +Generates a file named ``conanbuildinfo.props`` containing an XML that can be imported to your *Visual Studio* project. + +Generated xml structure: + +.. code-block:: xml + + + + + + + {ROOT DIRECTORY REQUIRE 1} + {ROOT DIRECTORY REQUIRE 2} + + + {BIN DIRECTORY REQUIRE 1};{BIN DIRECTORY REQUIRE 2};$(ExecutablePath) + + + PATH=%PATH%;{BIN DIRECTORY REQUIRE 1};{BIN DIRECTORY REQUIRE 2}; + WindowsLocalDebugger + + + + {INCLUDE DIRECTORY REQUIRE 1};{INCLUDE DIRECTORY REQUIRE 2};%(AdditionalIncludeDirectories) + %(PreprocessorDefinitions) + %(AdditionalOptions) + + + {LIB DIRECTORY REQUIRE 1};{LIB DIRECTORY REQUIRE 2};%(AdditionalLibraryDirectories) + {LIB NAMES REQUIRE1} {LIB NAMES REQUIRE 2} %(AdditionalDependencies) + %(AdditionalOptions) + + + + \ No newline at end of file diff --git a/reference/generators/xcode.rst b/reference/generators/xcode.rst new file mode 100644 index 000000000000..65856f7c8b29 --- /dev/null +++ b/reference/generators/xcode.rst @@ -0,0 +1,32 @@ +.. _xcode_generator: + +xcode +===== + +.. container:: out_reference_box + + This is the reference page for ``xcode`` generator. + Go to :ref:`Integrations/Xcode` if you want to learn how to integrate your project or recipes with Visual Studio. + + + + +The **xcode** generator creates a file named ``conanbuildinfo.xcconfig`` that can be imported to your *XCode* project. + +The file declare these variables: + ++--------------------------------+----------------------------------------------------------------------+ +| VARIABLE | VALUE | ++================================+======================================================================+ +| HEADER_SEARCH_PATHS | The requirements `include dirs` | ++--------------------------------+----------------------------------------------------------------------+ +| LIBRARY_SEARCH_PATHS | The requirements `lib dirs` | ++--------------------------------+----------------------------------------------------------------------+ +| OTHER_LDFLAGS | `-lXXX` corresponding to library names | ++--------------------------------+----------------------------------------------------------------------+ +| GCC_PREPROCESSOR_DEFINITIONS | The requirements definitions | ++--------------------------------+----------------------------------------------------------------------+ +| OTHER_CFLAGS | The requirements cflags | ++--------------------------------+----------------------------------------------------------------------+ +| OTHER_CPLUSPLUSFLAGS | The requirements cxxflags | ++--------------------------------+----------------------------------------------------------------------+ \ No newline at end of file diff --git a/reference/generators/ycm.rst b/reference/generators/ycm.rst new file mode 100644 index 000000000000..cfb3fbbeff71 --- /dev/null +++ b/reference/generators/ycm.rst @@ -0,0 +1,7 @@ +.. _ycm_generator: + +youcompleteme +============= + + +! PENDING \ No newline at end of file diff --git a/reference/tools.rst b/reference/tools.rst index d7bbaeff7067..7f37e69f2221 100644 --- a/reference/tools.rst +++ b/reference/tools.rst @@ -5,15 +5,28 @@ Tools ===== Under the tools module there are several functions and utilities that can be used in conan package -recipes +recipes: -cpu_count() ------------ +.. code-block:: python + :emphasize-lines: 2 + + from conans import ConanFile + from conans import tools + + class ExampleConan(ConanFile): + ... + + +.. _cpu_count: + +tools.cpu_count() +----------------- Returns the number of CPUs available, for parallel builds. If processor detection is not enabled, it will safely return 1. +Can be overwritten with the environment variable ``CONAN_CPU_COUNT`` and configured in the :ref:`conan.conf file`. -vcvars_command() ----------------- +tools.vcvars_command() +---------------------- This function returns, for given settings, the command that should be called to load the Visual Studio environment variables for a certain Visual Studio version. It does not execute @@ -39,8 +52,8 @@ This is typically not needed if using ``CMake``, as the cmake generator will han Visual Studio version. -unzip() -------- +tools.unzip() +------------- Function mainly used in ``source()``, but could be used in ``build()`` in special cases, as when retrieving pre-built binaries from the Internet. @@ -69,8 +82,9 @@ So, use only this option if you are sure that the zip file was created correctly -untargz() ---------- +tools.untargz() +--------------- + Extract tar gz files (or in the family). This is the function called by the previous ``unzip()`` for the matching extensions, so generally not needed to be called directly, call ``unzip()`` instead unless the file had a different extension. @@ -83,8 +97,9 @@ unless the file had a different extension. # or to extract in "myfolder" sub-folder tools.untargz("myfile.tar.gz", "myfolder") -get() ------ +tools.get() +----------- + Just a high level wrapper for download, unzip, and remove the temporary zip file once unzipped. Its implementation is very straightforward: @@ -97,8 +112,9 @@ is very straightforward: os.unlink(filename) -download() ----------- +tools.download() +---------------- + Retrieves a file from a given URL into a file with a given filename. It uses certificates from a list of known verifiers for https downloads, but this can be optionally disabled. You can also specify the number of retries in case of fail with ``retry`` parameter and the seconds to wait before download attempts @@ -115,8 +131,8 @@ with ``retry_wait``. tools.download("http://someurl/somefile.zip", "myfilename.zip", retry=2, retry_wait=5) -replace_in_file() ------------------ +tools.replace_in_file() +----------------------- This function is useful for a simple "patch" or modification of source files. A typical use would be to augment some library existing ``CMakeLists.txt`` in the ``source()`` method, so it uses @@ -132,8 +148,9 @@ conan dependencies without forking or modifying the original project: include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake) conan_basic_setup()''') -check_with_algorithm_sum() --------------------------- + +tools.check_with_algorithm_sum() +-------------------------------- Useful to check that some downloaded file or resource has a predefined hash, so integrity and security are guaranteed. Something that could be typically done in ``source()`` method after @@ -162,8 +179,8 @@ via ``hashlib.new(algorithm_name)``. The previous is equivalent to: "eb599ec83d383f0f25691c184f656d40384f9435") -patch() -------- +tools.patch() +------------- Applies a patch from a file or from a string into the given path. The patch should be in diff (unified diff) format. To be used mainly in the ``source()`` method. @@ -195,8 +212,11 @@ Then it can be done specifying the number of folders to be stripped from the pat patch(patch_file="file.patch", strip=1) -environment_append() --------------------- + +.. _environment_append_tool: + +tools.environment_append() +-------------------------- This is a context manager that allows to temporary use environment variables for a specific piece of code in your conanfile: @@ -213,10 +233,8 @@ in your conanfile: When the context manager block ends, the environment variables will be unset. - - -chdir() -------- +tools.chdir() +------------- This is a context manager that allows to temporary change the current directory in your conanfile: @@ -231,8 +249,8 @@ This is a context manager that allows to temporary change the current directory .. _build_sln_commmand: -build_sln_command() -------------------- +tools.build_sln_command() +------------------------- Returns the command to call `devenv` and `msbuild` to build a Visual Studio project. It's recommended to use it along with ``vcvars_command()``, so that the Visual Studio tools @@ -253,8 +271,8 @@ Arguments: * **upgrade_project** True/False. If True, the project file will be upgraded if the project's VS version is older than current -pythonpath() ------------- +tools.pythonpath() +------------------ This is a context manager that allows to load the PYTHONPATH for dependent packages, create packages with python code, and reuse that code into your own recipes. @@ -279,8 +297,8 @@ file or folder with a ``whatever`` file or object inside, and should have declar self.env_info.PYTHONPATH.append(self.package_folder) -human_size() ------------- +tools.human_size() +------------------ Will return a string from a given number of bytes, rounding it to the most appropriate unit: Gb, Mb, Kb, etc. It is mostly used by the conan downloads and unzip progress, but you can use it if you want too. @@ -293,14 +311,15 @@ It is mostly used by the conan downloads and unzip progress, but you can use it >> 1Kb -OSInfo and SystemPackageTool ----------------------------- +tools.OSInfo and tools.SystemPackageTool +---------------------------------------- These are helpers to install system packages. Check :ref:`system_requirements` +.. _run_in_windows_bash_tool: -run_in_windows_bash -------------------- +tools.run_in_windows_bash +------------------------- Runs an unix command inside the msys2 environment. It requires to have MSYS2 in the path. Useful to build libraries using ``configure`` and ``make`` in Windows. Check :ref:`Building with Autotools ` section. @@ -313,22 +332,16 @@ Useful to build libraries using ``configure`` and ``make`` in Windows. Check :re tools.run_in_windows_bash(self, command) # self is a conanfile instance -unix_path ---------- +tools.unix_path +--------------- Used to translate Windows paths to MSYS/CYGWIN unix paths like c/users/path/to/file -escape_windows_cmd ------------------- +tools.escape_windows_cmd +------------------------ Useful to escape commands to be executed in a windows bash (msys2, cygwin etc). - Adds escapes so the argument can be unpacked by CommandLineToArgvW() - Adds escapes for cmd.exe so the argument survives cmd.exe's substitutions. - - - - - -