= Conan Basic Example
:toc:
:toc-placement!:

toc::[]

# Introduction

link:http://conan.io[Conan] supports downloading libraries and making them available to an application developers. Packages are defined in the link:https://docs.conan.io/en/latest/using_packages/conanfile_txt.html[+conanfile.txt+] file, which defines packages, options, and the link:https://docs.conan.io/en/latest/reference/generators.html#generators-reference[generators] for your project.

The files in this tutorial are below:

```
.
├── CMakeLists.txt
├── conanfile.txt
├── main.cpp
└── README.adoc
```

  * link:CMakeLists.txt[] - Contains the CMake commands to run
  * link:conanfile.txt[] - Contains the conan dependencies and options
  * link:main.cpp[] - Source file of the application.

# Concepts

## conanfile.txt

### requires

The conanfile.txt defines the required packages you wish to install

[source,ini]
----
[requires]
fmt/5.3.0@bincrafters/stable
----


Where:

  * `fmt` is the name of the package / library.
  * `5.3.0` is the version of the package.
  * `bincrafters` is the owner / builder of the package.
  * `stable` is channel of the package. Channels provide a to have different variants of packages.

### generators

Generators define the build systems that you are using and allows Conan to create files with all the information needed to find your libraries and link your program.

[source,ini]
----
[generators]
cmake
----

The CMake generator will create the file `conanbuildinfo.cmake` which should be included in your +CMakeLists.txt+ file. This will be a per-user file and should not be committed to your source control system.

## Installing Packages

To install packages you should run the following:

[source,bash]
----
$ mkdir build
$ cd build
$ conan install ..
----

This will tell conan to read the +conanfile.txt+ from your root folder and install any required package configurations. If the package is not available in your package cache it will be downloaded.

As per our requires section, `conan install` will download a static library version of fmtlib along with all required headers. On my system with default configuration, this cached library is as follows:

[source,bash]
----
$ ls ~/.conan/data/fmt/5.3.0/bincrafters/stable/package/4d887c1c2779c63d2cdd81580698d2e22cb35b29/
conaninfo.txt  conanmanifest.txt  include  lib  licenses  share
$ ls ~/.conan/data/fmt/5.3.0/bincrafters/stable/package/4d887c1c2779c63d2cdd81580698d2e22cb35b29/lib
cmake  libfmt.a
----

The install command will also create any temporary files such as the +conanbuildinfo.cmake+ file.

## conanbuildinfo.cmake

As mentioned the +conanbuildinfo.cmake+ file contains any CMake commands that are required to link against your installed libraries. You must include this file in your CMakeLists.txt as follows

[source,cmake]
----
include(${CMAKE_BINARY_DIR}/conanbuildinfo.cmake)
conan_basic_setup()
----

The +CMAKE_BINARY_DIR+ here is the same build directory that your ran `conan install` in and will eventually run your `cmake` command in. 

Once included the variable +CONAN_LIBS+ is made available which contains the information you need to link against the libraries.

[source,cmake]
----
# link against the fmt target supplied by conan
target_link_libraries(third_party_include
    PRIVATE
        ${CONAN_LIBS}
)
----

# Building the Example

[source,bash]
----
$ mkdir build

$ cd build/

$ conan install ..
Configuration:
[settings]
arch=x86_64
arch_build=x86_64
build_type=Release
compiler=gcc
compiler.libcxx=libstdc++11
compiler.version=5
os=Linux
os_build=Linux
[options]
[build_requires]
[env]

fmt/5.3.0@bincrafters/stable: Not found in local cache, looking in remotes...
fmt/5.3.0@bincrafters/stable: Trying with 'conan-center'...
Downloading conanmanifest.txt
[==================================================] 166B/166B        
Downloading conanfile.py
[==================================================] 2.9KB/2.9KB      
Downloading conan_export.tgz
[==================================================] 758B/758B        
Decompressing conan_export.tgz: 1.98kB [00:00, 504kB/s]                  
fmt/5.3.0@bincrafters/stable: Downloaded recipe revision 0
conanfile.txt: Installing package
Requirements
    fmt/5.3.0@bincrafters/stable from 'conan-center' - Downloaded
Packages
    fmt/5.3.0@bincrafters/stable:4d887c1c2779c63d2cdd81580698d2e22cb35b29 - Download

fmt/5.3.0@bincrafters/stable: Retrieving package 4d887c1c2779c63d2cdd81580698d2e22cb35b29 from remote 'conan-center' 
Downloading conanmanifest.txt
[==================================================] 1.1KB/1.1KB      
Downloading conaninfo.txt
[==================================================] 550B/550B        
Downloading conan_package.tgz
[==================================================] 156.2KB/156.2KB  
Decompressing conan_package.tgz: 161kB [00:00, 13.8MB/s]                   
fmt/5.3.0@bincrafters/stable: Package installed 4d887c1c2779c63d2cdd81580698d2e22cb35b29
fmt/5.3.0@bincrafters/stable: Downloaded package revision 0
conanfile.txt: Generator cmake created conanbuildinfo.cmake
conanfile.txt: Generator txt created conanbuildinfo.txt
conanfile.txt: Generated conaninfo.txt
conanfile.txt: Generated graphinfo

$ cmake ..
-- The C compiler identification is GNU 5.4.0
-- The CXX compiler identification is GNU 5.4.0
-- Check for working C compiler: /usr/bin/cc
-- Check for working C compiler: /usr/bin/cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Detecting C compile features
-- Detecting C compile features - done
-- Check for working CXX compiler: /usr/bin/c++
-- Check for working CXX compiler: /usr/bin/c++ -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Conan: Adjusting output directories
-- Conan: Using cmake global configuration
-- Conan: Adjusting default RPATHs Conan policies
-- Conan: Adjusting language standard
-- Current conanbuildinfo.cmake directory: /home/devuser/ws/build
-- Conan: Compiler GCC>=5, checking major version 5
-- Conan: Checking correct version: 5
-- Configuring done
-- Generating done
-- Build files have been written to: /home/devuser/ws/build

$ make VERBOSE=1
/usr/bin/cmake -H/home/devuser/ws -B/home/devuser/ws/build --check-build-system CMakeFiles/Makefile.cmake 0
/usr/bin/cmake -E cmake_progress_start /home/devuser/ws/build/CMakeFiles /home/devuser/ws/build/CMakeFiles/progress.marks
make -f CMakeFiles/Makefile2 all
make[1]: Entering directory '/home/devuser/ws/build'
make -f CMakeFiles/third_party_include.dir/build.make CMakeFiles/third_party_include.dir/depend
make[2]: Entering directory '/home/devuser/ws/build'
cd /home/devuser/ws/build && /usr/bin/cmake -E cmake_depends "Unix Makefiles" /home/devuser/ws /home/devuser/ws /home/devuser/ws/build /home/devuser/ws/build /home/devuser/ws/build/CMakeFiles/third_party_include.dir/DependInfo.cmake --color=
Dependee "/home/devuser/ws/build/CMakeFiles/third_party_include.dir/DependInfo.cmake" is newer than depender "/home/devuser/ws/build/CMakeFiles/third_party_include.dir/depend.internal".
Dependee "/home/devuser/ws/build/CMakeFiles/CMakeDirectoryInformation.cmake" is newer than depender "/home/devuser/ws/build/CMakeFiles/third_party_include.dir/depend.internal".
Scanning dependencies of target third_party_include
make[2]: Leaving directory '/home/devuser/ws/build'
make -f CMakeFiles/third_party_include.dir/build.make CMakeFiles/third_party_include.dir/build
make[2]: Entering directory '/home/devuser/ws/build'
[ 50%] Building CXX object CMakeFiles/third_party_include.dir/main.cpp.o
/usr/bin/c++    -I/home/devuser/.conan/data/fmt/5.3.0/bincrafters/stable/package/4d887c1c2779c63d2cdd81580698d2e22cb35b29/include  -std=gnu++11 -o CMakeFiles/third_party_include.dir/main.cpp.o -c /home/devuser/ws/main.cpp
[100%] Linking CXX executable bin/third_party_include
/usr/bin/cmake -E cmake_link_script CMakeFiles/third_party_include.dir/link.txt --verbose=1
/usr/bin/c++          CMakeFiles/third_party_include.dir/main.cpp.o  -o bin/third_party_include  -L/home/devuser/.conan/data/fmt/5.3.0/bincrafters/stable/package/4d887c1c2779c63d2cdd81580698d2e22cb35b29/lib -lfmt -Wl,-rpath,/home/devuser/.conan/data/fmt/5.3.0/bincrafters/stable/package/4d887c1c2779c63d2cdd81580698d2e22cb35b29/lib 
make[2]: Leaving directory '/home/devuser/ws/build'
[100%] Built target third_party_include
make[1]: Leaving directory '/home/devuser/ws/build'
/usr/bin/cmake -E cmake_progress_start /home/devuser/ws/build/CMakeFiles 0

$ ./bin/third_party_include 
Hello, conan. This is fmtlib!
----
