From 9707802f9bdcdd1062af85a50546619b8266282e Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Tue, 16 Aug 2022 14:18:16 -0700 Subject: [PATCH 01/12] docs: capture our policy for the options `shared` and `fPIC` This came as a question on Slack, thought it was worth writting down https://cpplang.slack.com/archives/C41CWV9HA/p1660683315599809 --- docs/reviewing.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/reviewing.md b/docs/reviewing.md index 969c407ec85c4..905e27f25d072 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -87,6 +87,15 @@ Where the SPDX guidelines do not apply, packages should do the following: - When no license is provided or when it's given to the "public domain", the value should be set to [Unlicense](https://spdx.org/licenses/Unlicense) as per [KB-H056](error_knowledge_base.md#kb-h056-license-public-domain) and [FAQ](faqs.md#what-license-should-i-use-for-public-domain). - When a custom (e.g. project specific) license is given, the value should be set to `LicenseRef-` as a prefix, followed by the name of the file which contains a custom license. See [this example](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/fft/all/conanfile.py#L8). For more details, [read this conversation](https://github.com/conan-io/conan-center-index/pull/4928/files#r596216206) +## Predeinfed Options and Known Defaults + +ConanCenter supports many combinations, these are outline in the [supported configurations](supported_platforms_and_configurations.md) document for each platform. + +The following known options for compiled libraries are defined: + +- shared: default should be set to `False` +- fPIC: should be set to `True` + ## Exporting Patches It's ideal to minimize the number of files in a package the exactly whats required. When recipes support multiple versions with differing patches it's strongly encourged to only export the patches that are being used for that given recipe. From 5b0ff88daa63b960313266e119fca2b728df10bc Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Thu, 8 Sep 2022 09:18:41 -0700 Subject: [PATCH 02/12] move everything to packing policy --- docs/faqs.md | 3 +- docs/packaging_policy.md | 62 ++++++++++++++++++++++++++++++++++------ docs/reviewing.md | 36 ----------------------- 3 files changed, 55 insertions(+), 46 deletions(-) diff --git a/docs/faqs.md b/docs/faqs.md index d69b2aaa245f7..e0826fd1524bd 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -236,8 +236,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..296eba322a54e 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -108,29 +108,48 @@ 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 +### Predeinfed Options and Known Defaults + +ConanCenter supports many combinations, these are outline in the [supported configurations](supported_platforms_and_configurations.md) document for each platform. + +* `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. + > 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 be removed. + + ```python + def config_options(self): + if self.settings.os == "Windows": + del self.options.fPIC + + def configure(self): + if self.options.shared: + del self.options.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 +160,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 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. diff --git a/docs/reviewing.md b/docs/reviewing.md index 037f2e9fc0d96..4b972979f0d6d 100644 --- a/docs/reviewing.md +++ b/docs/reviewing.md @@ -87,15 +87,6 @@ Where the SPDX guidelines do not apply, packages should do the following: - When no license is provided or when it's given to the "public domain", the value should be set to [Unlicense](https://spdx.org/licenses/Unlicense) as per [KB-H056](error_knowledge_base.md#kb-h056-license-public-domain) and [FAQ](faqs.md#what-license-should-i-use-for-public-domain). - When a custom (e.g. project specific) license is given, the value should be set to `LicenseRef-` as a prefix, followed by the name of the file which contains a custom license. See [this example](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/fft/all/conanfile.py#L8). For more details, [read this conversation](https://github.com/conan-io/conan-center-index/pull/4928/files#r596216206) -## Predeinfed Options and Known Defaults - -ConanCenter supports many combinations, these are outline in the [supported configurations](supported_platforms_and_configurations.md) document for each platform. - -The following known options for compiled libraries are defined: - -- shared: default should be set to `False` -- fPIC: should be set to `True` - ## Exporting Patches It's ideal to minimize the number of files in a package the exactly whats required. When recipes support multiple versions with differing patches it's strongly encourged to only export the patches that are being used for that given recipe. @@ -188,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 From c84c3781ce84572ae8dcce913d1074d8229b1a09 Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Fri, 9 Sep 2022 09:10:38 -0700 Subject: [PATCH 03/12] Update docs/packaging_policy.md --- docs/packaging_policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index 296eba322a54e..f8becb03d4a88 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -117,7 +117,7 @@ ConanCenter supports many combinations, these are outline in the [supported conf * `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. + > **Note**: The CI applies `shared=True` only to the package being built, while every other requirement will. It's important to keep this in mind when trying to consume shared packages from ConanCenter. > 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. From aa21b2b7cbb187d0880f2f3bfeb89783ab3d1a49 Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Fri, 9 Sep 2022 15:30:13 -0700 Subject: [PATCH 04/12] Update docs/packaging_policy.md --- docs/packaging_policy.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index f8becb03d4a88..ac1cfa2489402 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -131,7 +131,10 @@ ConanCenter supports many combinations, these are outline in the [supported conf def configure(self): if self.options.shared: - del self.options.fPIC + try: + del self.options.fPIC + except Exception: + pass ``` * `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 From 495ab55fa24b14eb51ccb902f0f0a643e623f9fa Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Wed, 14 Sep 2022 08:42:21 -0600 Subject: [PATCH 05/12] Update docs/packaging_policy.md --- docs/packaging_policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index ac1cfa2489402..50484607c4e99 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -126,7 +126,7 @@ ConanCenter supports many combinations, these are outline in the [supported conf ```python def config_options(self): - if self.settings.os == "Windows": + if self.settings.os == "Windows": del self.options.fPIC def configure(self): From dac03a6c1a3365b6adb229db07c8cb11b2062dfd Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Wed, 14 Sep 2022 08:47:44 -0600 Subject: [PATCH 06/12] Apply sse4s suggest --- docs/packaging_policy.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index 50484607c4e99..56236296b7c2a 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -112,7 +112,10 @@ in this direction. However, there are a couple of options that have a special me ### Predeinfed Options and Known Defaults -ConanCenter supports many combinations, these are outline in the [supported configurations](supported_platforms_and_configurations.md) document for each platform. +ConanCenter supports many combinations, these are outline in the [supported configurations](supported_platforms_and_configurations.md) document for each platform. +By default, `shared=False` is compiled 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`. From 5cb77b6b84d7e287c0978842c42728aa5b2a20f9 Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Wed, 14 Sep 2022 09:01:58 -0600 Subject: [PATCH 07/12] Add original q to faq and link to new docs --- docs/faqs.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/faqs.md b/docs/faqs.md index 99bea0defaddd..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. From 827aef63358f5ece868a9185b074f37df7e575ec Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Wed, 14 Sep 2022 11:30:20 -0600 Subject: [PATCH 08/12] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Francisco Ramírez --- docs/packaging_policy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index 56236296b7c2a..403ff45515330 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -110,7 +110,7 @@ for each combination. There are some particular cases for this general rule: 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. -### Predeinfed Options and Known Defaults +### 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, `shared=False` is compiled with `fPIC=True`. If support, `header_only=False` is the default. @@ -125,7 +125,7 @@ Usage of each option should follow the rules: > as their requirements were linked inside the shared library. See [FAQs](faqs.md#how-to-consume-a-graph-of-shared-libraries) for more information. * `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 be removed. + This option does not make sense on all the support configurations so it should be removed. ```python def config_options(self): @@ -169,7 +169,7 @@ Usage of each option should follow the rules: ### 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: +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_ From 7ae143ec968d57354dbe4bfead812d7ada4783b6 Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Wed, 14 Sep 2022 11:33:11 -0600 Subject: [PATCH 09/12] Note `rm_safe` --- docs/packaging_policy.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index 403ff45515330..c8c94853e5d0f 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -140,6 +140,14 @@ Usage of each option should follow the rules: 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). From 1a9c6b35df7905abc8efbc6d0aa9d95af35d7de8 Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Fri, 16 Sep 2022 14:20:44 -0700 Subject: [PATCH 10/12] Update docs/packaging_policy.md --- docs/packaging_policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index c8c94853e5d0f..c1611cce532b8 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -120,7 +120,7 @@ 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. 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. From 7d490646d761976d5c41e7e6501abfe23e3bff88 Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Fri, 16 Sep 2022 14:20:51 -0700 Subject: [PATCH 11/12] Update docs/packaging_policy.md --- docs/packaging_policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index c1611cce532b8..eb0058382372c 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -113,7 +113,7 @@ in this direction. However, there are a couple of options that have a special me ### 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, `shared=False` is compiled with `fPIC=True`. If support, `header_only=False` is the default. +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: From c9653ac4ea8c82185ad460cdef5ae385ba6c4bf1 Mon Sep 17 00:00:00 2001 From: Chris Mc Date: Mon, 19 Sep 2022 10:22:05 -0700 Subject: [PATCH 12/12] Update docs/packaging_policy.md Co-authored-by: Uilian Ries --- docs/packaging_policy.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/packaging_policy.md b/docs/packaging_policy.md index eb0058382372c..25757c36cc793 100644 --- a/docs/packaging_policy.md +++ b/docs/packaging_policy.md @@ -128,16 +128,16 @@ Usage of each option should follow the rules: 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 + 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