Conan 2.0 Recipe Migrations in ConanCenterIndex
- 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
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
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.
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
Importing this and adding it in we can finally replace some clutter, those old “subfolder properties” which were a convention in ConanCenterIndex.
\_build_subfoldercan be replaced by
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.
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
This change creates a lot of difference.
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
cmake.definitionscan be replaced by
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
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
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.
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.
There’s a few noteworthy Conan 2.0 changes:
- This is actually a migration pain point we are seeing in ConanCenterIndex, there are some trade-offs.
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.
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.
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
- Move the
- Copy the
- In the original
test_package/CMakeLists.txtremove the lines to the old generator
- Change the copied file
test_v1_package/CMakeLists.txtto pull the source files form the original location
../test_package/test_package.cppto not duplicate files
- Download the new
test_package/conanfile.pyfrom 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!