Skip to content

Latest commit

 

History

History
472 lines (290 loc) · 25.7 KB

error_knowledge_base.md

File metadata and controls

472 lines (290 loc) · 25.7 KB
Raw

Errors from the conan-center hook (KB-Hxxx)

#KB-H001: "DEPRECATED GLOBAL CPPSTD"

Conan > 1.15 deprecated the usage of the global cppstd setting in favor of compiler.cppstd to manage C++ standard. As a subsetting of the compiler, it shouldn't be declared in the conanfile.py.

#KB-H002: "REFERENCE LOWERCASE"

The package names in conan-center have to be lowercase. e.g: zlib/1.2.8.

#KB-H003: "RECIPE METADATA"

The recipe has to declare the following attributes:

Also we recommend adding topics attribute.

#KB-H005: "HEADER_ONLY, NO COPY SOURCE"

If the recipe calls self.info.header_only() in the package_id() method and doesn't declare settings, it should use the no_copy_source attribute to avoid unnecessary copies of the source code.

#KB-H006: "FPIC OPTION"

The recipe is not for a header-only library and should have an fPIC option:

class SomeRecipe(ConanFile):
    ...

    options = {"fPIC": [True, False]}
    default_options = {"fPIC": True}

#KB-H007: "FPIC MANAGEMENT"

The recipe declares fPIC but doesn't remove the option for Windows (where it doesn't make sense).

class SomeRecipe(ConanFile):
    ...

    def config_options(self):
        if self.settings.os == "Windows":
            del self.options.fPIC

Or, a package is built as shared library and fPIC is declared. The option fPIC should be removed:

class SomeRecipe(ConanFile):
    ...

    def configure(self):
        if self.options.shared:
            del self.options.fPIC

Here we use configure() method, because user options are loaded after config_options() only.

#KB-H008: "VERSION RANGES"

It is not allowed to use version ranges for the recipes in Conan center, where the dependency graph should be deterministic.

#KB-H009: "RECIPE FOLDER SIZE"

The recipe folder (including the test_package folder) cannot exceed 256KB.

#KB-H010: "IMMUTABLE SOURCES"

Create a file conandata.yml in the recipe folder containing the source code origins:

recipes/lib/1.2.0/conandata.yml:

sources:
  1.2.0:
    url: "http://downloads.sourceforge.net/project/mylib/1.2.0/sources.tar.gz"
    sha256: "36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d"

Then in the recipe, you can access the data to download the URL and validate the checksum doing:

class SomeRecipe(ConanFile):
    ...

    def source(self):
        tools.get(**self.conan_data["sources"][self.version])

#KB-H011: "LIBCXX MANAGEMENT"

If the library is detected as a pure C library (sources doesn't conatain any file with the following extensions: ["cc", "cpp", "cxx", "c++m", "cppm", "cxxm", "h++", "hh", "hxx", "hpp"]) then it has to remove the compiler.libcxx subsetting, because the cpp standard library shouldn't affect the binary ID:

class SomeRecipe(ConanFile):
    ...

    def configure(self):
        del self.settings.compiler.libcxx

#KB-H012: "PACKAGE LICENSE"

The binary packages should contain a folder named licenses containing the contents (library, tool, etc) license/s.

#KB-H013: "DEFAULT PACKAGE LAYOUT"

The binary packages shouldn't contain any other files or folder except the following: ["lib", "bin", "include", "res", "licenses"]. If you are packaging an application put all the contents inside the bin folder.

#KB-H014: "MATCHING CONFIGURATION"

The binary package contains some file that not corresponds to the configuration of the package, for example, binary libraries for a header-only library, a DLL file when the settings.os != Windows and so on. The error message will contain information about the offending file.

#KB-H015: "SHARED ARTIFACTS"

The binary package is shared (self.options.shared == True) but there is no dll, so or dylib files inside the package.

#KB-H016: "CMAKE-MODULES-CONFIG-FILES"

The binary package cannot contain module or config CMake files ("Find*.cmake", "*Config.cmake", "*-config.cmake"). The package shouldn't contain specific build-system files to inform to the consumers how to link with it. In order to make sure that the package will be consumed with any build-system, conan-center repository encourages to declare a def package_info(self) method with all the needed information about the package.

The consumers of the package will be able to consume the packages using a specific generators for the build system they use.

See also: Why are CMake find/config files and pkg-config files not packaged?.

#KB-H017: "PDB FILES NOT ALLOWED"

Because of the big size of the PDB files (Program Databse, a debug information format) and the issues using them changing the original folders, the PDB files are not allowed to be packaged.

See also: Why PDB files are not allowed?.

#KB-H018: "LIBTOOL FILES PRESENCE"

Packaging libtool files (*.la) instead of library files (*.a) is not allowed.

#KB-H019: "CMAKE FILE NOT IN BUILD FOLDERS"

Some file with *.cmake extension has been found in a folder not declared in cpp_info.builddirs. It is only allowed to put build files in builddirs because the generators might be able to include them when needed, but only if they are located in well known paths.

#KB-H020: "PC-FILES"

For the same reasons explained at KB-H016 it is not allowed to package *.pc files.

See also: Why are CMake find/config files and pkg-config files not packaged?.

#KB-H021: "MS RUNTIME FILES"

For the legal reasons, and in order to reduce the size of packages, it's not allowed to package Microsoft Visual Studio runtime libraries, such as msvcr80.dll, msvcp80.dll, vcruntime140.dll and so on.

#KB-H022: "CPPSTD MANAGEMENT"

If the library is detected as a pure C library (sources doesn't conatain any file with the following extensions: ["cc", "cpp", "cxx", "c++m", "cppm", "cxxm", "h++", "hh", "hxx", "hpp"]) then it has to remove the compiler.cppstd subsetting, because the cpp standard library shouldn't affect the binary ID:

class SomeRecipe(ConanFile):
    ...

    def configure(self):
        del self.settings.compiler.cppstd

#KB-H023: "EXPORT LICENSE"

A recipe should not export any license file, as all recipes are under the same license type (in the root of this repo).

class SomeRecipe(ConanFile):
    ...

    exports = "LICENSE.md" # not allowed

There is a complete explanation in the FAQ.

#KB-H024: "TEST PACKAGE FOLDER"

The test_package folder is required for every recipe in Conan Center Index.

. conanfile.py
. test_package
  |- conanfile.py

#KB-H025: "META LINES"

The following metadata lines (and similiar) are not allowed in recipes:

  • Shebang to specify Python version:
#!/usr/bin/env python  # not allowed
#!/usr/local/bin/python  # not allowed

class SomeRecipe(ConanFile):
    ...
  • Vim configuration:
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4 # not allowed

class SomeRecipe(ConanFile):
    ...
# -*- coding: utf-8 -*-  # not allowed
# coding=utf-16          # not allowed

class SomeRecipe(ConanFile):
    ...

#KB-H027: "CONAN CENTER INDEX URL"

The attribute url should point to the address where the recipe is located. The current Conan Center Index address is https://github.com/conan-io/conan-center-index

#KB-H028: "CMAKE MINIMUM VERSION"

All CMake files added to recipe package should contain a minimal version (Not necessarily 2.8.11, it can be any version) available in the file:

# CMakeLists.txt
cmake_minimum_required(VERSION 2.8.11)
project(conanwrapper)

...

#KB-H029: "TEST PACKAGE - RUN ENVIRONMENT"

The RunEnvironment() build helper is no longer needed in the test_package/conanfile.py. It has been integrated by run_environment parameter.

# test_package/conanfile.py
class TestConan(ConanFile):
    settings = "os", "compiler", "build_type", "arch"

    def test(self):
        self.run("bin/test", run_environment=True)

#KB-H030: "CONANDATA.YML FORMAT"

The structure of the conandata.yml file should follow the schema defined in Adding Packages - Conandata.yml Format.

#KB-H031: "CONANDATA.YML REDUCE"

This hook re-creates the information of the conandata.yml file, discarding the fields not relevant to the version of the package exported. This avoids creating new recipe revisions for every new change introduced in the file. Any additional field in the YAML file will raise an error.

#KB-H032: "SYSTEM REQUIREMENTS"

System requirements can be used as an option when a Conan package is not available ,the same package can be installed by system package manager. However, it can cause reproducibility problems, since the package may vary according the distribution or OS. Conan is not able to track its metadata, so that, installing system packages by recipe is not allowed.

See also: Can I install packages from the system package manager?.

#KB-H034: "TEST PACKAGE - NO IMPORTS()"

The method imports helps the test package stage copying all dynamic libraries and special resources. However, the run_environment parameter, used when running commands, is able to solve all paths to the dynamic libraries installed in your cache.

#KB-H037: "NO AUTHOR"

Since the entire community is maintaining all CCI recipes, putting just one name in a recipe is unfair, putting all names is unmanageable. All authors can be found in the Git logs.

#KB-H040: "NO TARGET NAME"

According the Conan issue #6269, the attribute cpp_info.name should be avoided for Conan Center Index in favor of cpp_info.names["cmake_find_package"] and cpp_info.names["cmake_find_package_multi"].

See also: Migrating legacy cpp_info attributes to set_property().

#KB-H041: "NO FINAL ENDLINE"

Source files should end with a final endline. This avoids potential warnings/errors like no new line at the end of file.

#KB-H044: "NO REQUIRES.ADD()"

Both self.requires.add() and self.build_requires.add() have been deprecated in favor of self.requires() and self.build_requires() which were introduced on Conan 1.x. Both add() were introduced during Conan 0.x and since Conan 1.23 they no longer follow the original behavior.

#KB-H045: "DELETE OPTIONS"

The method self.options.remove() was introduced in Conan 0.x, however, Conan 1.x brings a more pythonic way for removing options from your recipe: del self.options.<option_name>

See also: configure(), config_options().

#KB-H046: "CMAKE VERBOSE MAKEFILE"

The CMake definition CMAKE_VERBOSE_MAKEFILE helps for debugging when developing, however, for regular CI build, it increases the log size and it's only required when problems occur and need to be verified.

#KB-H048: "CMAKE VERSION REQUIRED"

The file test_package/CMakeLists.txt should require CMake 3.1 by default: cmake_minimum_required(VERSION 3.1). The CMake wrapper file can require CMake 2.8, because Conan recipe and the test package are totally separated. However, if CMAKE_CXX_STANDARD or CXX_STANDARD is explicit, CMake 3.1 is mandatory.

#KB-H049: "CMAKE WINDOWS EXPORT ALL SYMBOLS"

The CMakeLists.txt definitions CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS and WINDOWS_EXPORT_ALL_SYMBOLS are available since CMake 3.4 only. Any previous version will ignore it.

#KB-H050: "DEFAULT SHARED OPTION VALUE"

By default, all packages should be built as static library (the option shared is False in default_options). However, some projects can be restricted to shared library only, for those cases, open a new issue to include the package name in the allowlist.

#KB-H051: "DEFAULT OPTIONS AS DICTIONARY"

The attribue default_options should be a dictionary, for example default_options = {'shared': False, 'fPIC': True}.

#KB-H052: "CONFIG.YML HAS NEW VERSION"

It's important to have new library version defined in both config.yml and conandata.yml, otherwise newly added version will not be checked and built by CI and will not be available for download.

#KB-H053: "PRIVATE IMPORTS"

The recipe imports private Conan API, this is strongly discouraged - private imports are subjects to breaking changes. Avoid usage of private APIs, request to publicly expose needed methods, if necessary.

#KB-H054: "LIBRARY DOES NOT EXIST"

Libraries which are listed on Components must be present in libdirs. Check if the library name is correct, or if a library is only generated for a specific platform.

#KB-H055: "SINGLE REQUIRES"

Do not use requirements() method and self.requires attribute together in the same recipe. The duality creates a heterogeneous way of solving dependencies, making it difficult to review and susceptible to prone errors.

#KB-H056: "LICENSE PUBLIC DOMAIN"

Public Domain is not a license by itself, but consists of all the creative work to which no exclusive intellectual property rights apply. If a project is under Public Domain and there is no license listed, the Unlicense should be used as described in the FAQ.

#KB-H057: "TOOLS RENAME"

The rename() method will be the standard for Conan 2.0, and also, it uses robocopy, which is safer on Windows.

#KB-H058: "ILLEGAL CHARACTERS"

Windows naming conventions and reserved characters must be avoided for file naming, otherwise the will not be supported on Windows.

#KB-H059: "CLASS NAME"

Generic class names can cause review confusion. To keep a better naming, it should use <Package>Conan.

#KB-H060: "NO CRLF"

Files with CRLF as endline can cause CI errors when building a package, due the conversion to LF and false detection from CI as changed file. The .gitattributes file lists which files should be converted to LF when commit. However, if you want to enforce it in your local copy, you may run:

> git config --local core.autocrlf false
> git config --local core.eol lf

The core.autocrlf disabled means that git will not convert from CRLF to LF on commit. The core.eol sets the specific line ending to be used for every commit.

#KB-H062: "TOOLS CROSS BUILDING"

Replace all occurrences of tools.cross_building(self.settings) with tools.cross_building(self). When cross building, conan needs to compare self.settings and self.settings_build, which are attributes of self.

#KB-H064: "INVALID TOPICS"

An invalid topic has been detected. Remove or rename it. Right now, topic conan is considered redundant and it's not needed to explicitly list it within recipe.

#KB-H065: "NO REQUIRED_CONAN_VERSION"

The recipe misses required_conan_version attribute. It may happen due to the usage of new features within recipe (such as strip_root parameter of the tools.get helper). The policy of Conan Center Index to support only the latest version of the Conan Client, so it's safe to put the version Conan Center Index currently runs into the recipe. Otherwise, it's not an easy task on its own to determine the minimal version that has to be specified: checking the Conan Client Changelog, one has to know in which Conan Client releases all the attributes, methods, build helpers, etc. used by the recipe were first introduced, and then select the most recent of them. Consider adding the following code:

required_conan_version = ">=1.43.0"  # use the version that Conan Center Index runs

class SomeRecipe(ConanFile):
    ...

See also: Submitting a Package.

#KB-H066: "SHORT_PATHS USAGE"

The recipe missess short_paths attribute. It may happen due to the very long paths within source, build or package directories during the package creating. Consider adding the following code:

class SomeRecipe(ConanFile):
    ...

    short_paths = True

See also: Maximum Path Length Limitation.

#KB-H068: "TEST_TYPE MANAGEMENT"

In Conan 2.0, see migration guide, the test_package/conanfile.py needs to declare the requirement being tested explicitly. To be prepared you have to set the attribute test_type="explicit" (this will be ignored in 2.0) to make Conan activate the explicit mode, then declaring the requirement using the self.tested_reference_str that contains the reference being tested.

#KB-H069: "TEST PACKAGE - NO DEFAULT OPTIONS"

This is to ensure the exact package that is built and uploaded is tested against. When options of default_options are modified in a test_package it can possibly result in the graph being modified. The objective is to enforce quality of the packages and to avoid confusing "missing packages" errors.

#KB-H070: "MANDATORY SETTINGS"

ℹ️ This rule was put in place as it was deemed safe for evaluation however there is room for improvement

ConanCenter operates is profiles with a predefined list of settings, all of these much be present in the recipe to ensure package_ids are computed correctly. Some libraries, for instance header-only, do not require all the settings and those should be deleted from the package_id. This approach ensure consistency and reduces the learning curve.

Recipes should include:

class SomeRecipe(ConanFile):
    ...

    settings = "os", "compiler", "build_type", "arch"

  • For header-only recipes (example):

        def package_id(self):
        self.info.header_only()

There is the case when the package is header-only, but the options affects the generated artifact, (e.g. kanguru, pagmo2 ...), so you need to use self.info.settings.clear() instead.

  • For "tool" recipes (example) which only provide binaries, see our packing policy for more, should do as follows:

        def package_id(self):
        del self.info.settings.compiler

#KB-H071: "INCLUDE PATH DOES NOT EXIST"

It's erroneous to leave the default include directory when it's not present. Consider adding:

def package_info(self):
    self.cpp_info.includedirs = []

Deprecated errors

The following errors from the hooks are deprecated and no longer reported:

#KB-H047: "NO ASCII CHARACTERS"

According to PEP 263, Unicode literals should only appear in Python code if the encoding is declared on one of the first two lines of the source file. Without such a declaration, any Unicode literal will cause a syntax error for Python 2 interpreters.