Understanding the Conan Package layout

In the previous section, we introduced the concept of editable packages and mentioned that the reason they work out of the box when put in editable mode is due to the current definition of the information in the layout() method. Let’s examine this feature in more detail.

In this tutorial, we will continue working with the say/1.0 package and the hello/1.0 consumer used in the editable packages tutorial.

Please, first of all, clone the sources to recreate this project. You can find them in the examples2 repository in GitHub:

  1. $ git clone https://github.com/conan-io/examples2.git
  2. $ cd examples2/tutorial/developing_packages/package_layout

Note

We use CMake presets in this example. This requires CMake >= 3.23 because the “include” from CMakeUserPresets.json to CMakePresets.json is only supported since that version. If you prefer not to use presets you can use something like:

  1. cmake <path> -G <CMake generator> -DCMAKE_TOOLCHAIN_FILE=<path to
  2. conan_toolchain.cmake> -DCMAKE_BUILD_TYPE=Release

Conan will show the exact CMake command everytime you run conan install in case you can’t use the presets feature.

As you can see, the main folder structure is the same:

  1. .
  2. ├── hello
  3. │   ├── CMakeLists.txt
  4. │   ├── conanfile.py
  5. │   └── src
  6. │       └── hello.cpp
  7. └── say
  8.     ├── CMakeLists.txt
  9.     ├── conanfile.py
  10.     ├── include
  11.     │   └── say.h
  12.     └── src
  13.         └── say.cpp

The main difference here is that we are not using the predefined cmake_layout() in the say/1.0 ConanFile, but instead, we are declaring our own custom layout. Let’s see how we describe the information in the layout() method so that it works both when we create the package in the Conan local cache and also when the package is in editable mode.

say/conanfile.py

  1. import os
  2. from conan import ConanFile
  3. from conan.tools.cmake import CMake
  6. class SayConan(ConanFile):
  7.     name = "say"
  8.     version = "1.0"
  10.     exports_sources = "CMakeLists.txt", "src/*", "include/*"
  12.     ...
  14.     def layout(self):
  16.         ## define project folder structure
  18.         self.folders.source = "."
  19.         self.folders.build = os.path.join("build", str(self.settings.build_type))
  20.         self.folders.generators = os.path.join(self.folders.build, "generators")
  22.         ## cpp.package information is for consumers to find the package contents in the Conan cache
  24.         self.cpp.package.libs = ["say"]
  25.         self.cpp.package.includedirs = ["include"] # includedirs is already set to 'include' by
  26.                                                    # default, but declared for completion
  27.         self.cpp.package.libdirs = ["lib"]         # libdirs is already set to 'lib' by
  28.                                                    # default, but declared for completion
  30.         ## cpp.source and cpp.build information is specifically designed for editable packages:
  32.         # this information is relative to the source folder that is '.'
  33.         self.cpp.source.includedirs = ["include"] # maps to ./include
  35.         # this information is relative to the build folder that is './build/<build_type>', so it will
  36.         self.cpp.build.libdirs = ["."]  # map to ./build/<build_type> for libdirs
  38.     def build(self):
  39.         cmake = CMake(self)
  40.         cmake.configure()
  41.         cmake.build()

Let’s review the layout() method. You can see that we are setting values for self.folders and self.cpp. Let’s explain what these values do.

self.folders

Defines the structure of the say project for the source code and the folders where the files generated by Conan and the built artifacts will be located. This structure is independent of whether the package is in editable mode or exported and built in the Conan local cache. Let’s define the folder structure for the say package:

  1. say
  2.  ├── CMakeLists.txt
  3.  ├── conanfile.py
  4.  ├── include
  5.  │   └── say.h
  6.  ├── src
  7.  │   └── say.cpp
  8.  └── build
  9.      ├── Debug            --> Built artifacts for Debug
  10.      │   └── generators   --> Conan generated files for Debug config
  11.      └── Release          --> Built artifacts for Release
  12.          └── generators   --> Conan generated files for Release config

  • As we have our CMakeLists.txt in the . folder, self.folders.source is set to ..

  • We set self.folders.build to be ./build/Release or ./build/Debug depending on the build_type setting. These are the folders where we want the built binaries to be located.

  • The self.folders.generators folder is the location we set for all the files created by the Conan generators. In this case, all the files generated by the CMakeToolchain generator will be stored there.

Note

Please note that the values above are for a single-configuration CMake generator. To support multi-configuration generators, such as Visual Studio, you should make some changes to this layout. For a complete layout that supports both single-config and multi-config, please check the cmake_layout() in the Conan documentation.

self.cpp

This attribute is used to define where consumers will find the package contents (headers files, libraries, etc.) depending on whether the package is in editable mode or not.

cpp.package

First, we set the information for cpp.package. This defines the contents of the package and its location relative to the folder where the package is stored in the local cache. Please note that defining this information is equivalent to defining self.cpp_info in the package_info() method. This is the information we defined:

  • self.cpp.package.libs: we add the say library so that consumers know that they should link with it. This is equivalent to declaring self.cpp_info.libs in the package_info() method.

  • self.cpp.package.libdirs: we add the lib folder so that consumers know that they should search there for the libraries. This is equivalent to declaring self.cpp_info.libdirs in the package_info() method. Note that the default value for libdirs in both the cpp_info and cpp.package is ["lib"] so we could have omitted that declaration.

  • self.cpp.package.includedirs: we add the include folder so that consumers know that they should search there for the library headers. This is equivalent to declaring self.cpp_info.includedirs in the package_info() method. Note that the default value for includedirs in both the cpp_info and cpp.package is ["include"] so we could have omitted that declaration.

To check how this information affects consumers we are going to do first do a conan create on the say package:

  1. $ cd say
  2. $ conan create . -s build_type=Release

When we call conan create, Conan moves the recipe and sources declared in the recipe to be exported to the local Cache to a recipe folder and after that, it will create a separate package folder to build the binaries and store the actual package contents. If you check in the [YOUR_CONAN_HOME]/p folder, you will find two new folders similar to these:

Tip

You could get the exact locations for this folders using the conan cache command or checking the output of the conan create command.

  1. <YOUR_CONAN_HOME>/p
  2. ├── sayb3ea744527a91      --> folder for sources
  3. │   └── ...
  4. │
  5. └── say830097e941e10      --> folder for building and storing the package binaries
  6.     ├── b
  7.     │   ├── build
  8.     │   │   └── Release
  9.     │   ├── include
  10.     │   │   └── say.h
  11.     │   └── src
  12.     │       ├── hello.cpp
  13.     │       └── say.cpp
  14.     └── p
  15.         ├── include       --> defined in cpp.package.includedirs
  16.         │   └── say.h
  17.         └── lib           --> defined in cpp.package.libdirs
  18.             └── libsay.a  --> defined in self.cpp.package.libs

You can identify there the structure we defined in the layout() method. If you build the hello consumer project now, it will search for all the headers and libraries of say in that folder inside the local Cache in the locations defined by cpp.package:

  1. $ cd ../hello
  2. $ conan install . -s build_type=Release
  4. # Linux, MacOS
  5. $ cmake --preset conan-release --log-level=VERBOSE
  6. # Windows
  7. $ cmake --preset conan-default --log-level=VERBOSE
  9. ...
  10. -- Conan: Target declared 'say::say'
  11. -- Conan: Library say found <YOUR_CONAN_HOME>p/say8938ceae216fc/p/lib/libsay.a
  12. -- Created target CONAN_LIB::say_say_RELEASE STATIC IMPORTED
  13. -- Conan: Found: <YOUR_CONAN_HOME>p/p/say8938ceae216fc/p/lib/libsay.a
  14. -- Configuring done
  15. ...
  17. $ cmake --build --preset conan-release
  18. [ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o
  19. [100%] Linking CXX executable hello
  20. [100%] Built target hello

cpp.source and cpp.build

We also defined cpp.source and cpp.build attributes in our recipe. These are only used when the package is in editable mode and point to the locations that consumers will use to find headers and binaries. We defined:

  • self.cpp.source.includedirs set to ["include"]. This location is relative to the self.folders.source that we defined to .. In the case of editable packages, this location will be the local folder where we have our project.

  • self.cpp.build.libdirs set to ["."]. This location is relative to the self.folders.build that we defined to ./build/<build_type>. In the case of editable packages, this location will point to <local_folder>/build/<build_type>.

Note that other cpp.source and cpp.build definitions are also possible, with different meanings and purposes, for example:

  • self.cpp.source.libdirs and self.cpp.source.libs could be used if we had pre-compiled libraries in the source repo, committed to git, for example. They are not a product of the build, but rather part of the sources.

  • self.cpp.build.includedirs could be use for folders containing headers generated at build time, as it usually happens by some code generators that are fired by the build before starting to compile the project.

To check how this information affects consumers, we are going to first put the say package in editable mode and build it locally.

  1. $ cd ../say
  2. $ conan editable add . --name=say --version=1.0
  3. $ conan install . -s build_type=Release
  4. $ cmake --preset conan-release
  5. $ cmake --build --preset conan-release

You can check the contents of the say project’s folder now, you can see that the output folders match the ones we defined with self.folders:

  1. .
  2. ├── CMakeLists.txt
  3. ├── CMakeUserPresets.json
  4. ├── build
  5. │   └── Release       --> defined in cpp.build.libdirs
  6. │       ├── ...
  7. │       ├── generators
  8. │       │   ├── CMakePresets.json
  9. │       │   ├── ...
  10. │       │   └── deactivate_conanrun.sh
  11. │       └── libsay.a  --> no need to define
  12. ├── conanfile.py
  13. ├── include           --> defined in cpp.source.includedirs
  14. │   └── say.h
  15. └── src
  16.     ├── hello.cpp
  17.     └── say.cpp

Now that we have the say package in editable mode, if we build the hello consumer project, it will search for all the headers and libraries of say in the folders defined by cpp.source and cpp.build:

  1. $ cd ../hello
  2. $ conan install . -s build_type=Release
  4. # Linux, MacOS
  5. $ cmake --preset conan-release --log-level=VERBOSE
  6. # Windows
  7. $ cmake --preset conan-default --log-level=VERBOSE
  9. ...
  10. -- Conan: Target declared 'say::say'
  11. -- Conan: Library say found <local_folder>/examples2/tutorial/developing_packages/package_layout/say/build/Release/libsay.a
  12. -- Conan: Found: <local_folder>/examples2/tutorial/developing_packages/package_layout/say/build/Release/libsay.a
  13. -- Configuring done
  14. ...
  16. $ cmake --build --preset conan-release
  17. [ 50%] Building CXX object CMakeFiles/hello.dir/src/hello.cpp.o
  18. [100%] Linking CXX executable hello
  19. [100%] Built target hello
  21. $ conan editable remove --refs=say/1.0

Note

Please, note that we did not define self.cpp.build.libs = ["say"]. This is because the information set in self.cpp.source and self.cpp.build will be merged with the information set in self.cpp.package so that you only have to define things that change for the editable package. For the same reason, you could also omit setting self.cpp.source.includedirs = ["include"] but we left it there to show the use of cpp.source.

See also