Skip to content

Commit

Permalink
New documentation about how to use Conan
Browse files Browse the repository at this point in the history
  • Loading branch information
@piponazo
piponazo committed Apr 11, 2018
1 parent a923b06 commit c80b1b9
Show file tree
Hide file tree
Showing 2 changed files with 249 additions and 30 deletions.
33 changes: 3 additions & 30 deletions README-CMAKE
View file
Original file line number Diff line number Diff line change
Expand Up @@ -183,43 +183,16 @@ We have three contributed CMake Build Environments:

It is possible to use CMake/MinGW if you put in some effort. This is documented in TODO-CMAKE.

5 Using conan to build exiv2 and project dependencies
5 Using conan to get the exiv2 project dependencies
=====================================================

Conan is a portable package manager for c++ (https://www.conan.io/). We added the option to use it
in Exiv2 so you can get all the Exiv2 dependencies (Expat, Zlib, Libcurl, Libssh) in a very easy
way. Basically, all you need to do is to have conan installed on your system and run the command
In README-CONAN.md we give explanations about how to use conan to get all the Exiv2 dependencies.
Basically, all you need to do is to have conan installed on your system and run the command
`conan install` before calling CMake:

$ mkdir build && cd build
$ conan install ..
$ cmake .. or cmake-gui ..

Conan will search for the dependencies in different repositories. Apart from the default public
conan repository, there exist others. We rely on the bincrafters's repo to handle some of our
dependencies. To add this remote to you conan configuration, run the following command:

$ conan remote add conan-bincrafters https://api.bintray.com/conan/bincrafters/public-conan

In case there are not available packages for your setup (OS + Compiler) you will see error messages
like this one:

```
PROJECT: WARN: Can't find a 'zlib/1.2.8@lasote/stable' package for the specified options and settings:
- Settings: arch=x86_64, build_type=Release, compiler=clang, compiler.version=3.9, os=Macos
- Options: shared=False

ERROR: Missing prebuilt package for 'zlib/1.2.8@lasote/stable'
Try to build it from sources with "--build zlib"
Or read "http://docs.conan.io/en/latest/faq/troubleshooting.html#error-missing-prebuilt-package"
```

To compile the dependencies from sources you will need to run the conan install command like this:

$ conan install ../ --profile clang --build missing

To learn more about Conan, please visit their documentation page:
http://docs.conan.io/en/latest/

# That's all Folks
##
246 changes: 246 additions & 0 deletions README-CONAN.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,246 @@
# 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.

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.

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')
```

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`

```bash
conan search -r conan-center zlib/1.2.11@conan/stable

# conan-center zlib/1.2.11@conan/stable (This is the recipe for which we were searching packages)

Package_ID: ff0b79bd9b0fc1d915200da2fe02ae326cef4b1b
[options]
shared: False
[settings]
arch: x86_64
build_type: Debug
compiler: gcc
compiler.exception: seh
compiler.threads: posix
compiler.version: 4.9
os: Windows
Outdated from recipe: False

Package_ID: ff5ec8938c949149b25b89d656bed297cd5d5aad
[options]
shared: False
[settings]
arch: x86
build_type: Debug
compiler: clang
compiler.version: 3.9
os: Linux
Outdated from recipe: False

Package_ID: ff82a1e70ba8430648a79986385b20a3648f8c19
[options]
shared: True
[settings]
arch: x86_64
build_type: Debug
compiler: Visual Studio
compiler.runtime: MDd
compiler.version: 15
os: Windows
Outdated from recipe: False
```

## Installation

There are several ways to install conan, but the recommended one is using **pip**.

```bash
pip install conan
```

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):

```bash
conan remote add conan-bincrafters https://api.bintray.com/conan/bincrafters/public-conan
```

## Basic usage

The first thing we need to do, is to check that conan was properly installed and you can access it:
```bash
$ 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:

```Ini
[build_requires]
[settings]
arch=x86_64
build_type=Release
compiler=Visual Studio
compiler.runtime=MD
compiler.version=15
os=Windows
arch_build=x86_64
os_build=Windows
[options]
[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**.

Then, we will create a build directory where we will run the conan commands and we access it:
```bash
$ mkdir build
$ cd build
```

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
```

The expected output should be something like this, in case it's the first time you run conan:
```bash
$ conan install ..
Expat/2.2.5@pix4d/stable: Retrieving from predefined remote 'conan-center'
Expat/2.2.5@pix4d/stable: Trying with 'conan-center'...
Downloading conanmanifest.txt
[==================================================] 220B/220B
Downloading conanfile.py
[==================================================] 1.7KB/1.7KB
zlib/1.2.11@conan/stable: Retrieving from predefined remote 'conan-center'
zlib/1.2.11@conan/stable: Trying with 'conan-center'...
Downloading conanmanifest.txt
[==================================================] 121B/121B
Downloading conanfile.py
[==================================================] 5.7KB/5.7KB
libcurl/7.56.1@bincrafters/stable: Retrieving from predefined remote 'bincrafters'
libcurl/7.56.1@bincrafters/stable: Trying with 'bincrafters'...
Downloading conanmanifest.txt
...
PROJECT: Installing D:\Dev\Windows\projects\exiv2\conanfile.py
Requirements
Expat/2.2.5@pix4d/stable from 'conan-center'
OpenSSL/1.0.2n@conan/stable from 'conan-center'
gtest/1.8.0@bincrafters/stable from 'conan-center'
libcurl/7.56.1@bincrafters/stable from 'bincrafters'
zlib/1.2.11@conan/stable from 'conan-center'
Packages
Expat/2.2.5@pix4d/stable:6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7
OpenSSL/1.0.2n@conan/stable:606fdb601e335c2001bdf31d478826b644747077
gtest/1.8.0@bincrafters/stable:a35f8fa327837a5f1466eaf165e1b6347f6e1e51
libcurl/7.56.1@bincrafters/stable:e37838f02fd790447943465f1c9317fd1c59b95c
zlib/1.2.11@conan/stable:6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7

PROJECT: Retrieving package 6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7
Expat/2.2.5@pix4d/stable: Looking for package 6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7 in remote 'conan-center'
Downloading conanmanifest.txt
[==================================================] 323B/323B
Downloading conaninfo.txt
[==================================================] 438B/438B
Downloading conan_package.tgz
[==================================================] 133.6KB/133.6KB
Expat/2.2.5@pix4d/stable: Package installed 6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7
PROJECT: Retrieving package a35f8fa327837a5f1466eaf165e1b6347f6e1e51
gtest/1.8.0@bincrafters/stable: Looking for package a35f8fa327837a5f1466eaf165e1b6347f6e1e51 in remote 'conan-center'
Downloading conanmanifest.txt
[==================================================] 3.5KB/3.5KB
Downloading conaninfo.txt
[==================================================] 478B/478B
Downloading conan_package.tgz
[==================================================] 1001.1KB/1001.1KB
gtest/1.8.0@bincrafters/stable: Package installed a35f8fa327837a5f1466eaf165e1b6347f6e1e51
PROJECT: Retrieving package 6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7
...
PROJECT: Generator cmake created conanbuildinfo.cmake
PROJECT: Generator txt created conanbuildinfo.txt
PROJECT: Generated conaninfo.txt
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).
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
- Options: shared=False
ERROR: Missing prebuilt package for 'zlib/1.2.11@conan/stable'
Try to build it from sources with "--build zlib"
Or read "http://docs.conan.io/en/latest/faq/troubleshooting.html#error-missing-prebuilt-package"
```
In that case, we still have the chance to compile the library by ourselves by telling conan to do so:
```bash
$ 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:
```bash
$ conan install ..
PROJECT: Installing D:\Dev\Windows\projects\exiv2\conanfile.py
Requirements
Expat/2.2.5@pix4d/stable from 'conan-center'
OpenSSL/1.0.2n@conan/stable from 'conan-center'
gtest/1.8.0@bincrafters/stable from 'conan-center'
libcurl/7.56.1@bincrafters/stable from 'bincrafters'
zlib/1.2.11@conan/stable from 'conan-center'
Packages
Expat/2.2.5@pix4d/stable:6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7
OpenSSL/1.0.2n@conan/stable:606fdb601e335c2001bdf31d478826b644747077
gtest/1.8.0@bincrafters/stable:a35f8fa327837a5f1466eaf165e1b6347f6e1e51
libcurl/7.56.1@bincrafters/stable:e37838f02fd790447943465f1c9317fd1c59b95c
zlib/1.2.11@conan/stable:6cc50b139b9c3d27b3e9042d5f5372d327b3a9f7
Expat/2.2.5@pix4d/stable: Already installed!
gtest/1.8.0@bincrafters/stable: Already installed!
zlib/1.2.11@conan/stable: Already installed!
OpenSSL/1.0.2n@conan/stable: Already installed!
libcurl/7.56.1@bincrafters/stable: Already installed!
PROJECT: Generator cmake created conanbuildinfo.cmake
PROJECT: Generator txt created conanbuildinfo.txt
PROJECT: Generated conaninfo.txt
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:
```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).
### 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.
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.

0 comments on commit c80b1b9

Please sign in to comment.