• Everything you need is available in 1.53, so you can prepare recipes ahead of time
  • Most of the changes are “search and replace”

I want to upgrade my personal project, and the community has done an amazing job upgrading recipes. More than I was even expecting. (and I review “most” of the PRs we get at ConanCenterIndex).

OpenSSL and Boost are missing but those are too involved for a blog, so the last one was RESTinio, which I will try to break down every change that’s needed to upgrade so you can upgrade your own recipes.

This is a Header only, but unlike most (usually they are just copy files), it’s a CMake based project so it’s relatively easy and comes with a few extra quirks. The only thing I will not cover (since it was already done) is the package_info “property names” for the new CMakeDeps generator. You can read about the New cpp_info.set_property model in the ConanCenter docs.

Updating the imports

All of the 2.0 methods are in the conan namespace… Notice the “s” is no longer there, this should make code reviews an easy way of spotting new versus old.

There’s a cheat sheet for more of the file IO and common imports in ConanCenterIndex. Most of the tools imports are now grouped conans.tools.Version is made available from conan.tools.scm

My recommendation is to look for tools. and add in the new imports for each then just replace it with an empty string then add back the self as the first argument. This will work for all but the rare case where a name was changed. You should be able to very quickly find the tool category in the 2.0 Reference documentation.

For those who wonder, why not add the category of the tools where they are being used, this is to follow the recommendations in tools import guidelines where the higher namespace is considered private and should not be used.

The only “surprise” is the import you will need to add. This is because some method were previously methods for the ConanFile, for instance self.copy will become copy(self, …) and this is exposed from the conan.tools.files. You will also need to change the source and destination for the files methods, the new static methods no longer assume the folder and require you to be explicit.

Just with changing the imports alone, you can see the difference between old versus new

diff updating imports

You might notice the only import being dropped was functools this is because the new Generators and build helpers… we’ll get to those soon.

Enabling Layouts

One of the key features in 2.0 that enables a lot of the improvements is Layouts. Since RESTinio is a CMake based project you would probably reach for the cmake_layout however this is tailored towards build and packaging libraries. This would probably work but this is a “less is more” situation… for Header-Only, i’d start with the basic_layout.

Importing this and adding it in we can finally replace some clutter, those old “subfolder properties” which were a convention in ConanCenterIndex.

diff adding layout

  • \_source_subfolder becomes source_folder
  • \_build_subfolder can be replaced by self.build_folder

diff removing subfolder properties

We get to do even more clean up. Since this is header-only, there is no “build folder” but we do configure CMake. This is now taken care of by the new conan.tools.cmake.CMake build helper. Since the basic_layout setups the property self.build_folder the CMake help takes full advantage of this.

adding basic layout

Switch to the new Generators

This recipe previously used the old cmake generator as an attribute… It should have used cmake_find_package_multi but let’s just pretend it did. These can be replaced with CMakeToolchain and CMakeDeps respectively.

This change creates a lot of difference.

diff new generator vs old helper

  • We no longer pass CMake configuration options to the build helper.

    • That responsibility with given to the new toolchain.
    • CMakeDeps will generate the files required for RESTinio’s calls to find_package

  • cmake.definitions can be replaced by tc.variables

The best part is cleanup! We can also remove the old generators attribute along with the old “cmake wrapper” that we used to use to call the old cmake generators include(conanbuildinfo.cmake) and conan_basic_setup()

diff build method

This is sadly where we uncover our first caveat… this “cmake wrapper” we used in ConanCenterIdex sometimes hides functionality. In this particular example, it directed the build help to the correct subfolder of RESTinio with its CMakeLists.txt. With add_subdirectory(source_subfolder/dev/restinio) so we will need to move this into the recipe.

Thankful this is a pretty common case and the new build helper can be configured correctly.

diff build methods pt2

We can simply pass the build_script_folder argument to let it know the “source folder” which will be used when it configures CMake.

Tackling the validate method

This is the most complicated part. In Conan 2.0 we will drop the Visual Studio compiler for the msvc compilers. There’s a lot of reason why, so it might be worth checking out the Conan Tribe Proposal where this was decided.

Thankfully we don’t need to think about this too much as the Community has already figured out the best way of going about this. Check the CMake Template Package from ConanCenterIndex we can see there’s a new helper check_min_vs that handles the new compiler.

diff validate mthod

There’s a few noteworthy Conan 2.0 changes:

  • self.settings.compiler became self.info.settings.compiler
    • This is actually a migration pain point we are seeing in ConanCenterIndex, there are some trade-offs.
  • check_min_vs is added

Also we no longer print warnings, this is because the convention in ConanCenter causes a lot of noise for the considerable group of users that have custom compilers or define their own with custom settings.

Updating package id

This is a pretty easy one, and generally the last step. The old header_only has been replaced with a clear to make it more obvious what it’s doing.

diff package id

Package info and cpp folders

We will once again need to add a few lines to help optimize the new generators.

The layout does a lot of work for use, including helping to set up the cpp_info with folders for binaries, frameworks, and libraries. As we are packaging a header only project, these need to be explicitly set to empty.

Test Package

This is an important part of the recipe since we still want to support 1.x all the while adding 2.0 support. There’s a lot of steps here but it’s pretty straightforward.

  • Create a new folder test_v1_package
  • Move the test_package/conanfile.py to test_v1_package
  • Copy the test_package/CMakeLists.txt to test_v1_package
  • In the original test_package/CMakeLists.txt remove the lines to the old generator

diff old test package cmake list

  • Change the copied file test_v1_package/CMakeLists.txt to pull the source files form the original location ../test_package/test_package.cpp to not duplicate files
  • Download the new test_package/conanfile.py from the ConanCenterIndex template

That should do it.

If you are looking for the full diff, you will be interested in https://github.com/conan-io/conan-center-index/pull/13338 which is the final product and was merged!