Workspaces [experimental]

Warning

This is an experimental feature. Actually, a preview of the feature, with the main goal of receiving feedback and improving it. Consider the file formats, commands and flows to be unstable and subject of change in next releases.

Sometimes, it is necessary to work simultaneously on more than one package. In theory, each package should be a “work unit”, and developers should be able to work on them in isolation. But sometimes, some changes require modifications in more than 1 package at the same time. The local development flow can help, but it still requires doing export-pkg to put the artifacts in the local cache, where other packages under development will consume them.

The conan workspaces allow to have more than one package in user folders, and have them to directly use other packages from user folders without needing to put them in the local cache.

Lets introduce them with a practical example:

$ git clone https://github.com/memsharded/conan-workspace-example.git
$ cd conan-workspace-example

Note this folder contains a file conanws.yml in the root, with the following contents:

HelloB:
    folder: B
    includedirs: src
    cmakedir: src
HelloC:
    folder: C
    includedirs: src
    cmakedir: src
HelloA:
    folder: A
    cmakedir: src

root: HelloA
generator: cmake
name: MyProject

Then, we will run a conan install as usual, using a build folder to output the dependencies information:

$ conan install . -if=build
Using conanws.yml file from C:\Users\<youruser>\conan-workspace-example
Workspace: Installing...
Requirements
    HelloA/root@project/develop from 'conanws.yml'
    HelloB/0.1@user/testing from 'conanws.yml'
    HelloC/0.1@user/testing from 'conanws.yml'
Packages
    HelloA/root@project/develop:8a1ff0ad9a2a372996a26ff4136faa83268b5442
    HelloB/0.1@user/testing:e5affb0ca4e5d6998c29f435daf78ab20ef50be5
    HelloC/0.1@user/testing:63da998e3642b50bee33f4449826b2d623661505

Workspace HelloC: Generator cmake created conanbuildinfo.cmake
Workspace HelloC: Generated conaninfo.txt
Workspace HelloC: Generated conanbuildinfo.txt
Workspace HelloB: Generator cmake created conanbuildinfo.cmake
Workspace HelloB: Generated conaninfo.txt
Workspace HelloB: Generated conanbuildinfo.txt
Workspace HelloA: Generator cmake created conanbuildinfo.cmake
Workspace HelloA: Generated conaninfo.txt
Workspace HelloA: Generated conanbuildinfo.txt

Note that nothing was really installed in the local cache, all the dependencies are resolved locally:

$ conan search
There are no packages

Also, all the generated conanbuildinfo.cmake for each dependencies were installed to the build folder. You can inspect them to check that the paths they define for their dependencies, are user folders, not pointing to the local cache.

As defined in the conanws.yml, a root CMakeLists.txt was generated for us. We can use it to generate the super-project and build it:

$ cd build
$ cmake .. -G "Visual Studio 14 Win64" # Adapt accordingly to your conan profile
# Now build it. You can also open your IDE and build
$ cmake --build . --config Release
$ ./A/Release/app.exe
Hello World C Release!
Hello World B Release!
Hello World A Release!

Now the project is editable, you can change the code of folder C hello.cpp to say “Bye World” and:

# Edit your C/src/hello.cpp file to say "Bye"
# Or press the build button of your IDE
$ cmake --build . --config Release
$ ./A/Release/app.exe
Bye World C Release!
Hello World B Release!
Hello World A Release!

In-source builds

The current approach with the super-project automatic generation, is only valid if all the opened packages are using the same build system, CMake. However, without using a super-project, it is still possible to use workspaces to simultaneously work on different packages with different build systems.

For this case, the conanws.yml won’t have the generator or name fields. The installation will be done without specifying a install folder:

$ conan install .

Each local package will have their own build folder, and the generated conanbuildinfo.cmake will be located in it. You can do local builds in each of the packages, and they will be referring and linking the other opened packages in user folders.

conanws.yml syntax

The conanws.yml file can be located in any parent folder of the location pointed by the conan install command. Conan will search up the folder hierarchy looking for a conanws.yml file. If it is not found, the normal conan install for a single package will be executed.

Any “opened” package will have an entry in the conanws.yml file. This entry will define the relative location of different folders:

HelloB:
    folder: B
    includedirs: src  # relative to B, i.e. B/src
    cmakedir: src # Where the CMakeLists.txt is, necessary for the super-project
    build: "'build' if '{os}'=='Windows' else 'build_{build_type}'.lower()"
    libdirs: "'build/{build_type}' if '{os}'=='Windows' else 'build_{build_type}'.lower()"

The build and libdirs local folders can be parameterized with the build type and the architecture (arch) if necessary, to account for different layouts and configurations.

The root field of conanws.yml defines which are the end consumers. They are needed as an input to define the dependency graph. There can be more than one root, in a comma separated list, but all of them will share the same dependency graph, so if they require different versions of the same dependencies, they will conflict.

root: HelloA, Other
generator: cmake # The super-project build system
name: MyProject # Name for the super-project

Known limitations

So far, only the CMake super-project generator is implemented. A Visual Studio one is being under development, and seems feasible, but it is ongoing work, not yet available.

Important

We really want your feedback. For any suggestion, problem, idea, please submit an issue to https://github.com/conan-io/conan/issues and use the [workspaces] prefix in the issue title.