New Cheat Sheet for Conan 2.0 is finally here!

This is the easiest way to see the exciting new features with Conan 2.0

Comparing 1.x and 2.0

One of the biggest changes is to the command line and this happens to shine with a visual

Obvious changes, new design and 1^st and 2^nd column switched places but that should not matter, we’ll refer to them by the opening section header.

Let’s dive into the changes.

Search Packages

It’s going to take a keen eye to notice the only change between these. If you spotted the /*, that’s the evidence of the unified references. This allows more granularity when specifying names, versions, users or channels. This change is also carried into recipes to access dependencies. See profile patterns for more details.

Consume Packages

This is where you are most likely to run into the changes.

Conan install

If the --requires jumped at you, that’s perfect. Notice the @ is missing? This is the change between 1.x and 2.0. How Conan distinguished between passing the CLI a reference or a path is much more explicit.
References lose the @ suffix and are explicitly called out by a dedicated argument --requires. This is true for all commands, not just the install command. This should alleviate misfortune cases where a reference has the same names as the path to its conanfile which leads to erroneous user inputs.

Note: When adding a user and/or channel the @ is still required, when there is no user the @ can be omitted.

Next is conan install <path>, for example ./conanfile.py if it’s in your current directory, this is unchanged. There are other considerations, such as layouts, where if you previously used --install-folder you may need to adapt this within the recipe.

Conanfile.txt with build system

This is where we are going to see the most changes, there are two big ones:

• We are using different generators
• There is now a layout section

[requires]
zlib/1.2.13

[generators]
cmake_find_package

[requires]
zlib/1.2.13

[generators]
CMakeToolchain
CMakeDeps

[layout]
cmake_layout

Note: Instead of listing different generators in the Conan 1.x column the example is more focused on CMake

This takes advantage of the features added in Conan 1.33. We used the new Generators CMakeToolchain and CMakeDeps and lastly leveraged layouts.

Tip: This is completely valid Conan 1.x syntax and if you are using this you’ll have a harder time switching to 2.0. Make sure to be on the latest Conan 1.x features as a part of your Migration Plan!

The layout is just as important as the updated Generators. Its role is to tell Conan where our code and build scripts are located. For this example the key role is to specify where to output the generated files. Without this Conan will spit everything out in the current directory.

With this in mind, if we look at the next command in the 1.x example, we used to do a mkdir build && cd build. We no longer need this because of the cmake_layout we declared in the 2.0 conanfile.txt.

All of this has a butterfly effect. Now that we no longer have to change directories (where the build folder is explicit in the declaration of our conanfile) the install commands changed ever so slightly with the path going from parent directory to current directory. One less character to type.

Note: Instead of listing different generators in the Conan 1.x column the example is more focused on CMake

If you have not heard or tried CMake Presets yet, you are missing out. This makes setting up a project way easier. This example requires CMake 3.23 or newer, but that’s not required as you can explicitly pass in with CMake as old as 3.15 the toolchain file -DCMAKE_TOOLCHAIN_FILE=build/generators/conan_toolchain.cmake. (the exact path varies depending on the CMake generator, platform, and settings so read the CLI output which will give you the correct one).

Client Configuration

This is going to be taking “Show local client configuration” and “configure local client” in addition to “add or modify client configurations”. We’ll also be comparing “Remote repository configurations”.

These sections got the most mixing up because

• conan config is much leaner
• conan user was moved to conan remote login

In order to make the comparison easier, I’ve reorganized the commands (from the old 1.x side) to match one to one (or none) with the new replacement

To start with, we have a command that’s highlighted for 2.0 cheat sheet but was not present for 1.x originally. This is one of the more requested features, opt-in default profiles. Managing profiles is one of the critical decisions for using Conan in CI/CD for DevOps. We have witnessed bad habits around relying on conan profile detect which limited the ability to improve the client. With Conan 2.0, there is no stability guaranteed for the detected configuration, this is something you should reconsider if you were doing conan config set which is also removed for the same reason. Alternative solutions are custom commands or managed profiles.

conan config list, this is a very simple command that shows all the available configurations one could possibly change. To display the value, conan config get was replaced by conan config show which takes a pattern which is the same as the values. For example tools.build.cmake.* to list all the CMake specific configurations current values defined in global.conf.

conan config install is unchanged and the recommended way of managing profiles, settings in 1.x and custom commands or extensions with 2.0.

conan profile show default gets the same -pr as conan install unified command line syntax at its best. conan profile show also works in 2.0 which should be a simplification while punching keys into a terminal.

Some straight forward commands to review:

• conan remote list – unchanged
• conan remote add – unchanged
• conan user was replaced with conan remote login.

Display Information

conan inspect is mostly unchanged, it’s still focused on local recipes. For migration, it dropped the -a attribute, this is replaced with structured output. You can add -f json for a more machine readable format to work with.

conan get was removed – a recipe by itself or accessing parts of a remotely hosted export/package was error prone and misused – instead you can use conan cache path to get the folder and then print the contents of the file however you like.

conan info was rolled into conan graph as a subcommand since they were very tightly coupled. It gains the same unified reference syntax that we saw with install hence the --requires here. The last command features --format html which is the new formatters syntax. This supports the HTML view that was present in Conan 1.x.

Creating a Package

Last but not least.

New has an updated syntax, along with update templates. This change was motivated to enable passing in more different inputs, for example some templates can be created with requirements, adding -d requires=pkg/0.1 to this example would achieve this.

Export is no longer featured but remains a useful command with the same functionality

Create is unchanged but does implement the new reference syntax along with removing deprecated flags.

Conan create is unchanged in this example however, the “filling in the reference” has changes, the name, version, user, channel are now passed with arguments with the same name instead of the 1.x reference syntax that was removed. conan create . 1.0.0@frog would now be conan create . –version 1.0.0 –user frog.

Upload a Package

There are a few subtle changes here, the reference used in the example previously matched any recipe starting with zlib, include zlib-ng which was not the intention, so now with the unified reference syntax it’s explicit matching only on the version since the / is present.
Our example remote was renamed, style points, but not indicative of anything functional.

Lastly --all is no longer present, this is now the default in 2.0 and there is now a --only-recipe for the old behavior.

Deploy outside the cache

There are 2 new features in the one snippet.

• Deployers
• No cache workflow (see last weeks blog to learn more)

Previously the old deploy generator only copied all the files to the local directory essentially unpacking the conan_package.tgz that would be on the remote. This has a few drawbacks and there were tons of requests for more specialized versions. This was replaced with Deployers. The new built-in full_deploy replaces the old one with the same functionality. It gained the support for other generators to be used in combination with deployers, such that the CMakeDeps will create files that use paths with the location inside the “full deploy” (i.e not reference the cache!). This is a long requested workflow that is now possible with 2.0.