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.

Sign up for GitHub

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

Jump to bottom

Added hooks management documentation #979

Merged
merged 1 commit into from
Dec 18, 2018
Merged

Added hooks management documentation #979

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 16 additions & 6 deletions extending/hooks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _hooks:

Hooks [EXPERIMENTAL]
======================
====================

.. warning::

Expand All @@ -11,7 +11,7 @@ The Conan hooks is a feature intended to extend the Conan functionalities and le
points.

Hook structure
----------------
--------------

Hooks are Python files containing **pre** and **post** functions that will be executed prior and after a determined task performed by the
Conan client. Those tasks could be Conan commands, recipe interactions such as exporting or packaging or interactions with the remotes.
Expand Down Expand Up @@ -148,7 +148,7 @@ Storage, activation and sharing
Hooks are Python files stored under *~/.conan/hooks* folder and **their file name should be the same used for activation** (without the
*.py* extension).

The activation of the hooks is done in the *conan.conf* section named ``[hooks]``. The hook names listed under this section will be
The activation of the hooks is done in the *conan.conf* section named ``[hooks]``. The hook names or paths listed under this section will be
considered activated.

.. code-block:: text
Expand All @@ -158,22 +158,32 @@ considered activated.
[hooks]
attribute_checker
conan-center
my_custom_hook/hook.py

They can be easily activated and deactivated from the command line using the :command:`conan config set` command:

.. code-block:: bash

$ conan config set hooks.attribute_checker # Activates 'attribute_checker'
$ conan config set hooks.my_custom_hook/hook.py # Activates 'my_custom_hook'

$ conan config rm hooks.attribute_checker # Deactivates 'attribute_checker'
$ conan config rm hooks.my_custom_hook/hook.py # Deactivates 'my_custom_hook'

There is also an environment variable ``CONAN_HOOKS`` to list the active hooks. Hooks listed in *conan.conf* will be loaded into
this variable and values in the environment variable will be used to load the hooks.

Hooks are considered part of the Conan client configuration and can be shared as usual with the :ref:`conan_config_install` command.
However, they can also be managed in isolated git repositories cloned into the *hooks* folder:

.. code-block:: bash

$ cd ~/.conan/hooks
$ git clone https://github.com/conan-io/hooks.git conan_hooks
$ conan set hooks.conan_hooks/hooks/conan-center.py

This way you can easily change from one version to another.

Official Hooks
----------------
--------------

There is a simple *attribute_checker* hook ready to be used in Conan. You can take it as a starting point to create your own ones.

Expand Down
14 changes: 8 additions & 6 deletions reference/commands/consumer/config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,11 +55,11 @@ It can get its configuration files from a local or remote zip file, from a local
files in the local Conan configuration.

The configuration may contain all or a subset of the allowed configuration files. Only the files that are present will be
replaced. The only exception is the **conan.conf** file for which only the variables declared will be installed,
replaced. The only exception is the *conan.conf* file for which only the variables declared will be installed,
leaving the other variables unchanged.

This means for example that **profiles** and **hooks** files will be overwritten if already present, but no profile or
hook file that the user has in the local machine will be deleted.
This means for example that **profiles** and **hooks** files will be overwritten if already present, but no profile or hook file that the
user has in the local machine will be deleted.

All the configuration files will be copied to the Conan home directory. These are the special files and the rules applied to merge them:

Expand All @@ -74,9 +74,11 @@ All the configuration files will be copied to the Conan home directory. These ar
+--------------------------------+----------------------------------------------------------------------+
| config/conan.conf | Merges the variables, overriding only the declared variables |
+--------------------------------+----------------------------------------------------------------------+
| hooks/my_hook.py | Overrides the local ~/.conan/hooks/my_hook.py if already exists |
+--------------------------------+----------------------------------------------------------------------+

The file *remotes.txt* is the only file listed above which does not have a direct counterpart in
the ``~/.conan`` folder. Its format is a list of entries, one on each line, with the form
the *~/.conan* folder. Its format is a list of entries, one on each line, with the form of

.. code-block:: text

Expand All @@ -90,8 +92,8 @@ definitions part of the *registry.txt* file uses the format required for *remote
provides a helpful starting point when writing a *remotes.txt* to be packaged in a Conan
client configuration.

The specified URL or path, the arguments used (if any) and the source type (from git, from dir, from zip file or from URL) will be stored in the
``general.config_install`` variable of the ``conan.conf`` file, so as following calls to :command:`conan config install` command doesn't
The specified URL or path, the arguments used (if any) and the source type (from git, from dir, from zip file or from URL) will be stored in
the ``general.config_install`` variable of the *conan.conf* file, so as following calls to :command:`conan config install` command doesn't
need to specify them.

**Examples**:
Expand Down