diff --git a/docs/faqs.md b/docs/faqs.md index 51f67dd65eab4..37533da405fe3 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -126,6 +126,10 @@ As stated earlier, any increase in the number of configurations will result in a We often receive new fixes and improvements to the recipes already available for x86_64, including help for other architectures like x86 and ARM. In addition, we also receive new cases of bugs, for recipes that do not work on a certain platform, but that are necessary for use, which is important to understand where we should put more effort. So we believe that the best way to maintain and add support for other architectures is through the community. +## Do static libraries tend to be compiled as PIC by default? + +Yes! You can learn more about default options in [Packing Policy](packing_policy.md#options). + ## Why PDB files are not allowed? The project initially decided not to support the PDB files primarily due to the size of the final package, which could add an exaggerated size and not even used by users. In addition, PDB files need the source code to perform the debugging and even follow the path in which it was created and not the one used by the user, which makes it difficult to use when compared to the regular development flow with the IDE. @@ -248,8 +252,7 @@ There are different motivations ## Why not add an option to build unit tests - Adding a testing option will change the package ID, but will not provide different packaged binaries -- Use the configuration [skip_test](packaging_policy.md#options) to define the testing behavior. - +- Use the configuration [skip_test](packaging_policy.md#options-to-avoid) to define the testing behavior. ## What is the policy for supported python versions? diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index 4eb95d041e21c..25757c36cc793 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -108,29 +108,62 @@ for each combination. There are some particular cases for this general rule: ## Options Recipes can list any number of options with any meaning, and defaults are up to the recipe itself. The CI cannot enforce anything -in this direction. However, there are a couple of options that have a special meaning for the CI: +in this direction. However, there are a couple of options that have a special meaning for the CI. -* `shared` (with values `True` or `False`). The CI inspects the recipe looking for this option. If it is found, it will +### Predefined Options and Known Defaults + +ConanCenter supports many combinations, these are outline in the [supported configurations](supported_platforms_and_configurations.md) document for each platform. +By default recipes should use `shared=False` with `fPIC=True`. If support, `header_only=False` is the default. + +Usage of each option should follow the rules: + +* `shared` (with values `True` or `False`). The CI inspects the recipe looking for this option. The **default should be `shared=False`** and will generate all the configurations with values `shared=True` and `shared=False`. - > Note.- The CI applies `shared=True` only to the package being built, while every other requirement will use their defaults - > (typically `shared=False`). It's important to keep this in mind when trying to consume shared packages from ConanCenter + > **Note**: The CI applies `shared=True` only to the package being built, while every other requirement will `shared=False`. To consume everything as a shared library you will set `--build=always` and/or `-o *:shared=True`) + > It's important to keep this in mind when trying to consume shared packages from ConanCenter > as their requirements were linked inside the shared library. See [FAQs](faqs.md#how-to-consume-a-graph-of-shared-libraries) for more information. -* `header_only` (with values `True` or `False`). If the CI detects this option, it will generate all the configurations for the - value `header_only=False` and add one more configuration with `header_only=True`. **Only one - package** will be generated for `header_only=True`, so it is crucial that the package is actually a _header only_ library, with header files only (no libraries or executables inside). +* `fPIC` (with values `True` or `False`). The **default should be `fPIC=True`** and will generate all the configurations with values `fPIC=True` and `fPIC=False`. + This option does not make sense on all the support configurations so it should be removed. + + ```python + def config_options(self): + if self.settings.os == "Windows": + del self.options.fPIC + + def configure(self): + if self.options.shared: + try: + del self.options.fPIC + except Exception: + pass + ``` + + Starting with Conan 1.53 this can be simplified to + + ```py + def configure(self): + if self.options.shared: + self.options.rm_safe("fPIC") + ``` + +* `header_only` (with values `True` or `False`). The **default should be `header_only=False`**. If the CI detects this option, it will generate all the + configurations for the value `header_only=False` and add one more configuration with `header_only=True`. **Only one package** + will be generated for `header_only=True`, so it is crucial that the package is actually a _header only_ library, with header files only (no libraries or executables inside). Recipes with such option should include the following in their `package_id` method ```python def package_id(self): if self.options.header_only: - self.info.header_only() + self.info.clear() ``` ensuring that, when the option is active, the recipe ignores all the settings and only one package ID is generated. +### Options to Avoid + * `build_testing` should not be added, nor any other related unit test option. Options affect the package ID, therefore, testing should not be part of that. Instead, use Conan config [skip_test](https://docs.conan.io/en/latest/reference/config_files/global_conf.html#tools-configurations) feature: @@ -141,3 +174,30 @@ in this direction. However, there are a couple of options that have a special me ``` The `skip_test` configuration is supported by [CMake](https://docs.conan.io/en/latest/reference/build_helpers/cmake.html#test) and [Meson](https://docs.conan.io/en/latest/reference/build_helpers/meson.html#test). + +### Recommended feature options names + +It's often needed to add options to toggle specific library features on/off. Regardless of the default, there is a strong preference for using positive naming for options. In order to avoid fragmentation, we recommend using the following naming conventions for such options: + +- enable_ / disable_ +- with_ / without_ +- use_ + +the actual recipe code then may look like: + +```py + options = {"use_tzdb": [True, False]} + default_options = {"use_tzdb": True} +``` + +```py + options = {"enable_locales": [True, False]} + default_options = {"enable_locales": True} +``` + +```py + options = {"with_zlib": [True, False]} + default_options = {"with_zlib": True} +``` + +having the same naming conventions for the options may help consumers, e.g. they will be able to specify options with wildcards: `-o *:with_threads=True`, therefore, `with_threads` options will be enabled for all packages in the graph that support it. diff --git a/docs/reviewing.md b/docs/reviewing.md index f42f88d67438b..4b972979f0d6d 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -179,33 +179,6 @@ target_link_libraries(${PROJECT_NAME} package::package) We encourage contributors to check that not only the _global_ target works properly, but also the ones for the components. It can be done creating and linking different libraries and/or executables. -## Recommended feature options names - -It's often needed to add options to toggle specific library features on/off. Regardless of the default, there is a strong preference for using positive naming for options. In order to avoid the fragmentation, we recommend to use the following naming conventions for such options: - -- enable_ / disable_ -- with_ / without_ -- use_ - -the actual recipe code then may look like: - -```py - options = {"use_tzdb": [True, False]} - default_options = {"use_tzdb": True} -``` - -```py - options = {"enable_locales": [True, False]} - default_options = {"enable_locales": True} -``` - -```py - options = {"with_zlib": [True, False]} - default_options = {"with_zlib": True} -``` - -having the same naming conventions for the options may help consumers, e.g. they will be able to specify options with wildcards: `-o *:with_threads=True`, therefore, `with_threads` options will be enabled for all packages in the graph that support it. - ## Supported Versions In this repository we are building a subset of all the versions for a given library. This set of version changes over time as new versions