Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation for workspaces #1086

Merged
merged 3 commits into from Mar 6, 2019
Merged
Changes from 1 commit
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

Just for now

Prev

review

  • Loading branch information...
memsharded committed Mar 6, 2019
commit e560a342bbc31e295b5bb866fa17bf5bfdf2272e
@@ -202,8 +202,8 @@ It is important to understand the evaluation order and priorities regarding the
folders specified without package reference won't be applied once a match is found.
- It no match is found, the original values for the layout folders defined in ``package_info()`` will
be respected.
- The layout file to be used is defined at ``conan editable add`` time. If a ``.conan/layouts/default`` file
is added after the ``conan editable add``, it will not be used at all.
- The layout file to be used is defined at :command:`conan editable add` time. If a ``.conan/layouts/default`` file
is added after the :command:`conan editable add`, it will not be used at all.


Using a package in editable mode
@@ -233,8 +233,8 @@ time, without any Conan command.

.. note::

When a package is in editable mode, most of the commands will not work. It is not possible to ``conan upload``,
``conan export`` or ``conan create`` when a package is in editable mode.
When a package is in editable mode, most of the commands will not work. It is not possible to :command:`conan upload`,
:command:`conan export` or :command:`conan create` when a package is in editable mode.

Revert the editable mode
------------------------
@@ -21,7 +21,7 @@ Lets introduce them with a practical example, the code can be found in the conan
.. code-block:: bash
$ git clone https://github.com/conan-io/examples.git
$ cd workspace/cmake
$ cd features/workspace/cmake
Note that this folder contains two files *conanws_gcc.yml* and *conan_vs.yml*, for gcc (Makefiles, single-configuration build environments)
@@ -90,8 +90,8 @@ is ``cmake`` and it will generate a *conanworkspace.cmake* file that looks like:
add_subdirectory(${PACKAGE_chat_SRC} ${PACKAGE_chat_BUILD})
endmacro()

This file can be included in your root *CMakeLists.txt* (this one is not generated, you provide it, so you can customize it
as much as you want), have a look to the one that is in the project:
This file can be included in your user-defined *CMakeLists.txt* (this file is not generated).
Here you can see the *CMakeLists.txt* used in this project:

.. code-block:: cmake

@@ -112,16 +112,17 @@ Single configuration build environments

There are some build systems, like Makefiles that requires the developer to manage different configurations in different build folders,
and switch between folders to change configuration. The above described file is *conan_gcc.yml* file, which defines a Conan workspace that
works for a CMake based project for MinGW/Unix Makefiles gcc environments.
works for a CMake based project for MinGW/Unix Makefiles gcc environments (working for apple-clang or clang would be very similar, if not identical).

Lets use it to install this workspace:

.. code-block:: bash
$ mkdir build_release && cd build_release
$ conan workspace install ../conanws_gcc.yml --profile=my_gcc_profile
$ conan workspace install ../conanws_gcc.yml --profile=my_profile
Here we assume that you have a ``my_gcc_profile`` profile defined, or you can avoid it if your default profile is already Gcc (Linux)
Here we assume that you have a ``my_profile`` profile defined which would use a single-configuration build system (like Makefiles). The
example is tested with gcc in Linux, but working with apple-clang with Makefiles would be the same).
You should see something like:

.. code-block:: bash
@@ -181,8 +182,8 @@ Note that nothing will really be installed in the local cache, all the dependenc

.. code-block:: bash
$ conan search
There are no packages
$ conan search say
There are no packages matching the 'say' pattern
.. note::
This conversation was marked as resolved by memsharded

This comment has been minimized.

Copy link
@jgsogo

jgsogo Feb 25, 2019

Member

Line above: make an explicit search for say, chat or hello, the user can have hundreds of projects already in the cache


@@ -263,8 +264,7 @@ the *hello/src/CMakeLists.txt* file:
The last ``conan_target_link_libraries(hello)`` is a helper that does the right linking with Debug/Release libraries (also works when using cmake
targets).

Lets use this. Note it is very important to install both Debug and Release configurations straight ahead, if we want to later switch between them
in the IDE:
Make sure to install both Debug and Release configurations straight ahead, if we want to later switch between them in the IDE:

.. code-block:: bash
@@ -299,8 +299,8 @@ the *layout_vs* define the ``[build_folder]`` not as ``build/{settings.build_typ
Notes
-----

Not that this way of developing packages shouldn't be used to create the final packages (you could try to use ``conan export-pkg``), but instead,
a full package creation with ``conan create`` (best in CI) is recommended.
Note that this way of developing packages shouldn't be used to create the final packages (you could try to use :command:`conan export-pkg`), but instead,
a full package creation with :command:`conan create` (best in CI) is recommended.

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

@@ -8,7 +8,7 @@ conan workspace
$ conan workspace [-h] {install} ...
command to manage workspaces
Command to manage workspaces

.. code-block:: text

@@ -68,17 +68,9 @@ conan workspace install
defaults. e.g., -s compiler=gcc
-u, --update Check updates exist from upstream remotes
This conversation was marked as resolved by memsharded

This comment has been minimized.

Copy link
@jgsogo

jgsogo Feb 25, 2019

Member

I would add a note saying that some of these options don't apply to packages referenced in the workspace definition file, I suppose that those ones are not being built or looked for in the remotes... those packages must be present in advance, no?

Opens the package ``<reference>`` in editable mode in the user folder ``<path>``
.. code-block:: text
positional arguments:
path Path to the package folder in the user workspace
reference Package reference e.g.: mylib/1.X@user/channel
optional arguments:
-h, --help show this help message and exit
-l LAYOUT, --layout LAYOUT
Relative or absolute path to a file containing the
layout. Relative paths will be resolved first relative
to current dir, then to local cache "layouts" folder
Note that these arguments, like ``settings`` and ``options`` mostly apply to the dependencies,
but those packages that are defined as editable in the workspace are in the user space.
Those packages won't be built by the command (even with ``--build`` arguments), as they are
built locally. It is the responsibility of the editables layout to match the settings (typically
parameterizing the layout with ``settings`` and ``options``)
@@ -40,7 +40,7 @@ This file can live in the conan cache, in the ``.conan/layouts`` folder, or in a
inside the source repo.

If there exists a ``.conan/layouts/default`` layout file in the cache and no layout file is specified
in the ``conan editable add <path> <reference>`` command, that file will be used.
in the :command:`conan editable add <path> <reference>` command, that file will be used.

The ``[source_folder]`` and ``[build_folder]`` are useful for workspaces. For example, when using ``cmake``
workspace-generator, it will locate the ``CMakeLists.txt`` of each package in editable mode in the
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.