diff --git a/README-CONAN.md b/README-CONAN.md index 8b14667e..becf73f3 100644 --- a/README-CONAN.md +++ b/README-CONAN.md @@ -1,15 +1,19 @@ # How to use conan -Conan is a portable package manager for C/C++ libraries. It can be used for bringing all the dependencies needed to build Exiv2 into local directories, without needing to install system packages. +Conan is a portable package manager for C/C++ libraries. It can be used for bringing all the dependencies needed to +build Exiv2 into local directories, without needing to install system packages. -This document provides a step-by-step guide to show you the basic usage of conan. For more details about the tool, please visit their [documentation website](http://docs.conan.io/en/latest/). +This document provides a step-by-step guide to show you the basic usage of conan. For more details about the tool, +please visit their [documentation website](http://docs.conan.io/en/latest/). ## Main concepts -Even when the following instructions will allow you to use conan directly, we strongly recommend to take a look to their "Getting started" [page](http://docs.conan.io/en/latest/getting_started.html), to better understand the main concepts. +Even when the following instructions will allow you to use conan directly, we strongly recommend to take a look to their +"Getting started" [page](http://docs.conan.io/en/latest/getting_started.html), to better understand the main concepts. -In the root level of the **Exiv2** repository, there is a file named `conanfile.py` that defines the C/C++ dependencies of the project. One of the dependencies is **Expat**, and it is stated like this: +In the root level of the **Exiv2** repository, there is a file named `conanfile.py` that defines the C/C++ dependencies +of the project. One of the dependencies is **Expat**, and it is stated like this: ```python self.requires('Expat/2.2.5@pix4d/stable') @@ -17,7 +21,11 @@ self.requires('Expat/2.2.5@pix4d/stable') The syntax stands for: `Library/version@user/channel`. -Conan will search for these dependencies in a list of remotes. In those servers there are recipes (the python code that explains how to build a library from its sources) and binary packages (different versions of the library for several combinations of configurations: Platform/Compiler/Settings). If there is already a packages for your configuration, conan will fetch them. Otherwise, it will compile the libraries for you by using the instructions provided in the recipe. To better illustrate this idea, here we show a list of packages that is returned by the command `conan search` +Conan will search for these dependencies in a list of remotes. In those servers there are recipes (the python code that +explains how to build a library from its sources) and binary packages (different versions of the library for several +combinations of configurations: Platform/Compiler/Settings). If there is already a packages for your configuration, +conan will fetch them. Otherwise, it will compile the libraries for you by using the instructions provided in the +recipe. To better illustrate this idea, here we show a list of packages that is returned by the command `conan search` ```bash conan search -r conan-center zlib/1.2.11@conan/stable @@ -69,9 +77,12 @@ There are several ways to install conan, but the recommended one is using **pip* pip install conan ``` -For other installation methods (brew, installers, from sources), visit this [link]([install conan](http://docs.conan.io/en/latest/installation.html)). +For other installation methods (brew, installers, from sources), visit this [link]([install +conan](http://docs.conan.io/en/latest/installation.html)). -By default, conan only point to few public conan repositories. However you can add more easily. We rely in the usage of the bincrafters's repository to find some of the dependencies. Therefore, we will need to add it to the list of remotes (we only need to do this once): +By default, conan only point to few public conan repositories. However you can add more easily. We rely in the usage of +the bincrafters's repository to find some of the dependencies. Therefore, we will need to add it to the list of remotes +(we only need to do this once): ```bash conan remote add conan-bincrafters https://api.bintray.com/conan/bincrafters/public-conan @@ -85,7 +96,9 @@ $ conan --version Conan version 1.1.1 ``` -The first time you run conan, it will auto-detect your configuration and store it in a default profile in the file $HOME/.conan/profiles/default. In case you are using Windows, and have a installation of Visual Studio 2017, the default profile will look like this: +The first time you run conan, it will auto-detect your configuration and store it in a default profile in the file +$HOME/.conan/profiles/default. In case you are using Windows, and have a installation of Visual Studio 2017, the default +profile will look like this: ```Ini [build_requires] @@ -102,7 +115,9 @@ os_build=Windows [env] ``` -But normally you will want to define new profiles for choosing different compilers (msvc, gcc, clang), different build_type (Release, Debug), runtimes (MD, MT, MDd, MTd), etc. Let´s create a copy of the default profile and name if **msvc2017Release**. +But normally you will want to define new profiles for choosing different compilers (msvc, gcc, clang), different +build_type (Release, Debug), runtimes (MD, MT, MDd, MTd), etc. Let´s create a copy of the default profile and name if +**msvc2017Release**. Then, we will create a build directory where we will run the conan commands and we access it: ```bash @@ -110,7 +125,8 @@ $ mkdir build $ cd build ``` -Finally, we use the `conan install` command pointing to the directory where the `conanfile.py` is, to bring the dependencies: +Finally, we use the `conan install` command pointing to the directory where the `conanfile.py` is, to bring the +dependencies: ```bash $ conan install .. --profile msvc2017Release ``` @@ -175,9 +191,11 @@ PROJECT imports(): Copied 5 '.dll' files (conan) ``` -Note that it first downloads the recipes, and then the binary packages. In this case everything went well, conan found the recipes in the remotes, and it also found packages for our configuration (msvc2017, Release, MD). +Note that it first downloads the recipes, and then the binary packages. In this case everything went well, conan found +the recipes in the remotes, and it also found packages for our configuration (msvc2017, Release, MD). -However, if you use other configuration for which there are not packages in the remotes, you will get an error similar to this: +However, if you use other configuration for which there are not packages in the remotes, you will get an error similar +to this: ```bash PROJECT: WARN: Can't find a 'zlib/1.2.11@conan/stable' package for the specified options and settings: - Settings: arch=x86_64, build_type=Release, compiler=clang, compiler.version=3.9, os=Macos @@ -194,7 +212,8 @@ In that case, we still have the chance to compile the library by ourselves by te $ conan install ../ --profile MyEsotericProfile --build missing ``` -Once the command succeeds, we will have the libraries in our system (you can find the recipes and packages in `$HOME/.conan/data`). Any new call to `conan install` with the same profile, will produce this output: +Once the command succeeds, we will have the libraries in our system (you can find the recipes and packages in +`$HOME/.conan/data`). Any new call to `conan install` with the same profile, will produce this output: ```bash $ conan install .. @@ -225,22 +244,33 @@ PROJECT imports(): Copied 5 '.dll' files Indicating that the packages were found in the local cache. -That´s all. After a successful call to `conan install`, some files will be generated in the `build` folder that will allow to CMake (or other systems) to find the headers and libraries of the dependencies handled by conan. By simply running: +That´s all. After a successful call to `conan install`, some files will be generated in the `build` folder that will +allow to CMake (or other systems) to find the headers and libraries of the dependencies handled by conan. By simply +running: ```bash $ cmake .. ``` -CMake should manage to configure the project finding all the dependencies. If you want to know more about how to use CMake in this project, refer to [README-CMAKE](README-CMAKE). +CMake should manage to configure the project finding all the dependencies. If you want to know more about how to use +CMake in this project, refer to [README-CMAKE](README-CMAKE). ### Windows specific notes -Some people have difficulties when starting to use conan + CMake + Visual Studio, but most of them are due to the lack of awareness in some details off the tool chain. In the previous section, the call `cmake ..` from a terminal, will pick a default CMake generator, that will depend on different factors. +Some people have difficulties when starting to use conan + CMake + Visual Studio, but most of them are due to the lack +of awareness in some details off the tool chain. In the previous section, the call `cmake ..` from a terminal, will pick +a default CMake generator, that will depend on different factors. -To choose a specific generator you can use the option `-G "Generator Name"`. If in your conan profile, you use a 64bits architecture (`arch: x86_64`), and you want to use a Visual Studio generator, you will need to indicate it in the first CMake call: +To choose a specific generator you can use the option `-G "Generator Name"`. If in your conan profile, you use a 64bits +architecture (`arch: x86_64`), and you want to use a Visual Studio generator, you will need to indicate it in the first +CMake call: ```bash cmake -G "Visual Studio 15 2017 Win64" -DCMAKE_BUILD_TYPE=Release ... ``` -It is also important to remark that, even when you can change the build type within Visual Studio once you open the solution generated by CMake, the dependencies brought by conan will use a specific configuration. If you try to mix conan dependencies that use a certain Visual Studio Runtime (example: `MD`), and try to compile Exiv2 with other one (example: `MT`), you will obtain linking errors. In order to make experiments with different runtime options, it is preferable to have different build folders. \ No newline at end of file +It is also important to remark that, even when you can change the build type within Visual Studio once you open the +solution generated by CMake, the dependencies brought by conan will use a specific configuration. If you try to mix +conan dependencies that use a certain Visual Studio Runtime (example: `MD`), and try to compile Exiv2 with other one +(example: `MT`), you will obtain linking errors. In order to make experiments with different runtime options, it is +preferable to have different build folders.