Skip to content

Latest commit

 

History

History
386 lines (235 loc) · 17.8 KB

error_knowledge_base.md

File metadata and controls

386 lines (235 loc) · 17.8 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. 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 fields: url, license, description and homepage. Also we recommend adding topics.

#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.

#KB-H017: "PDB FILES NOT ALLOWED"

Because of the big size of the PDB files and the issues using them changing the original folders, the PDB files are not allowed to be packaged.

#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.

#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):
    ...
  • Encoding:
# -*- 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 this schema:

sources:
  "1.69.0":
    url: "url1.69.0"
    sha256: "sha1.69.0"
  "1.70.0":
    url: "url1.70.0"
    sha256: "sha1.70.0"
patches:
  "1.70.0":
    - patch_file: "001-1.70.0.patch"
      base_path: "source_subfolder/1.70.0"
    - url: "https://fake_url.com/custom.patch"
      sha256: "sha_custom"
      base_path: "source_subfolder"
  "1.71.0":
    - patch_file: "001-1.71.0.patch"
      base_path: "source_subfolder/1.71.0"

#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 requires can be used as an option when a Conan package is not available the same package can be installer 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.

#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"].

#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>

#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 publically 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() and self.requires 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.

#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 .gitattribute 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.

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.