From f85a7c8aff42846e625d48d4caf70f367f025aea Mon Sep 17 00:00:00 2001 From: memsharded Date: Sun, 19 Feb 2023 12:56:42 +0100 Subject: [PATCH] more guidelines --- knowledge/guidelines.rst | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/knowledge/guidelines.rst b/knowledge/guidelines.rst index be6daa290fe8..b2b78c6dea37 100644 --- a/knowledge/guidelines.rst +++ b/knowledge/guidelines.rst @@ -5,16 +5,17 @@ Core guidelines Good practices -------------- -- The recipes' ``generate()`` method purpose is to prepare the build as much as possible. +- **build() should be simple, prepare the builds in generate() instead**: + The recipes' ``generate()`` method purpose is to prepare the build as much as possible. Users calling ``conan install`` will execute this method, and the generated files should allow users to do "native" builds (calling directly "cmake", "meson", etc.) as easy as possible. Thus, avoiding as much as possible any logic in the ``build()`` method, and moving it to the ``generate()`` method helps developers achieve the same build locally as the one that would be produced by a ``conan create`` build in the local cache. -- Always use your own profiles in production, instead of relying on the auto-detected profile, +- **Always use your own profiles in production**, instead of relying on the auto-detected profile, as the output of such auto detection can vary over time, resulting in unexpected results. Profiles (and many other configuration), can be managed with ``conan config install``. -- Developers should not be able to upload to "development" and "production" repositories in the server. +- **Developers should not be able to upload to "development" and "production" repositories** in the server. Only CI builds have write permissions in the server. Developers should only have read permissions and at most to some "playground" repositories used to work and share things with colleagues, but which packages are never used, moved or copied to the development or production repositories. @@ -24,27 +25,41 @@ Good practices building and running an executable that uses the headers and links against a packaged library should be enough. Such execution should be as simple as possible too. Any kind of unit and functional tests should be done in the ``build()`` method. -- Keep ``python_requires`` as simple as possible. Avoid transitive ``python_requires``, keep them +- **Keep ``python_requires`` as simple as possible**. Avoid transitive ``python_requires``, keep them as reduced as possible, and at most, require them explicitly in a "flat" structure, without ``python_requires`` requiring other ``python_requires``. Avoid inheritance (via ``python_requires_extend``) if not strictly necessary, and avoid multiple inheritance at all costs, as it is extremely complicated, and it does not work the same as the built-in Python one. +- At the moment the **Conan cache is not concurrent**. Avoid any kind of concurrency or parallelism, + for example different parallel CI jobs should use different caches (with CONAN_HOME env-var). This might + change in the future and we will work on providing concurrency in the cache, but until then, + use isolated caches for concurrent tasks. Forbidden practices ------------------- -- Calling the Conan process from Conan itself cannot be done. That includes calling +- **Conan is not re-entrant**: Calling the Conan process from Conan itself cannot be done. That includes calling Conan from recipe code, hooks, plugins, and basically every code that already executes when Conan is called. Doing it will result in undefined behavior. For example it is not valid to run ``conan search`` from a ``conanfile.py``. This includes indirect calls, like running Conan from a build script (like ``CMakeLists.txt``) while this build script is already being - executed as a result of a Conan invocation. -- The Conan Python API can only be called from Conan custom commands or from user Python scripts, + executed as a result of a Conan invocation. For the same reason **Conan Python API cannot be used from recipes**: The Conan Python API can only be called from Conan custom commands or from user Python scripts, but never from ``conanfile.py`` recipes, hooks, extensions, plugins, or any other code executed by Conan. -- Conan ``conanfile.py`` recipes user attributes and methods should always start with ``_``. +- **Recipes reserved names**: Conan ``conanfile.py`` recipes user attributes and methods should always start with ``_``. Conan reserves the "public" namespace for all attributes and methods, and ``_conan`` for private ones. Using any non-documented Python function, method, class, attribute, even if it is "public" in the Python sense, is undefined behavior if such element is not documented in this documentation. +- **Conan artifacts are immutable**: Conan packages and artifacts, once they are in the Conan cache, they are assumed to be immutable. + Any attempt to modify the exported sources, the recipe, the conandata.yml or any of the exported + or the packaged artifacts, is undefined behavior. For example, it is not possible to modify the + contents of a package inside the ``package_info()`` method or the ``package_id()`` method, those + methods should never modify, delete or create new files inside the packages. If you need to modify + some package, you might use your own custom ``deployer``. +- **Conan cache paths are internal implementation detail**: The Conan cache paths are an internal implementation detail. Conan recipes provide abstractions + like ``self.build_folder`` to represent the necessary information about folders, and commands + like ``conan cache path`` to get information of the current folders. The Conan cache might + be checked while debugging, as read-only, but it is not allowed to edit, modify or delete + artifacts or files from the Conan cache by any other means that Conan command line or public API.