(#14856) docs: Move build system examples to new file

* docs: Move build system examples to new file

* Apply suggestions from code review

Co-authored-by: SSE4 <tomskside@gmail.com>

Co-authored-by: SSE4 <tomskside@gmail.com>

docs/adding_packages/README.md

@@ -19,14 +19,6 @@ You can follow the three steps (:one: :two: :three:) described below! :tada:
     * [`conandata.yml`](#conandatayml)
     * [The _recipe folder_: `conanfile.py`](#the-_recipe-folder_-conanfilepy)
     * [Test Folders](#test-folders)
-  * [How to provide a good recipe](#how-to-provide-a-good-recipe)
-    * [Header Only](#header-only)
-    * [CMake](#cmake)
-      * [Components](#components)
-    * [Autotools](#autotools)
-      * [Components](#components-1)
-    * [No Upstream Build Scripts](#no-upstream-build-scripts)
-    * [System Packages](#system-packages)
   * [Test the recipe locally](#test-the-recipe-locally)
     * [Hooks](#hooks)
     * [Linters](#linters)<!-- endToc -->
@@ -171,44 +163,6 @@ a minimal project to test the package is strictly required. You can read about i
 
 Learn more about the ConanCenterIndex requirements in the [test packages](test_packages.md) document.
 
-## How to provide a good recipe
-
-The [recipes](https://github.com/conan-io/conan-center-index/tree/master/recipes) available in CCI can be used as good examples, you can use them as the base for your recipe. However it is important to note Conan features change over time and our best practices evolve so some minor details may be out of date due to the vast number of recipes.
-
-### Header Only
-
-If you are looking for header-only projects, you can take a look on [header-only template](../package_templates/header_only).
-Also, Conan Docs has a section about [how to package header-only libraries](https://docs.conan.io/en/latest/howtos/header_only.html).
-
-### CMake
-
-For C/C++ projects which use CMake for building, you can take a look on [cmake package template](../package_templates/cmake_package).
-
-#### Components
-
-Another common use case for CMake based projects, both header only and compiled, is _modeling components_ to match the `find_package` and export the correct targets from Conan's generators. A basic examples of this is [cpu_features](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpu_features/all/conanfile.py), a moderate/intermediate example is [cpprestsdk](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpprestsdk/all/conanfile.py), and a very complex example is [OpenCV](https://github.com/conan-io/conan-center-index/blob/master/recipes/opencv/4.x/conanfile.py).
-
-### Autotools
-
-However, if you need to use autotools for building, you can take a look on [libalsa](https://github.com/conan-io/conan-center-index/blob/master/recipes/libalsa/all/conanfile.py), [kmod](https://github.com/conan-io/conan-center-index/blob/master/recipes/kmod/all/conanfile.py), [libcap](https://github.com/conan-io/conan-center-index/blob/master/recipes/libcap/all/conanfile.py).
-
-#### Components
-
-Many projects offer **pkg-config**'s `*.pc` files which need to be modeled using components. A prime example of this is [Wayland](https://github.com/conan-io/conan-center-index/blob/master/recipes/wayland/all/conanfile.py).
-
-### No Upstream Build Scripts
-
-For cases where a project only offers source files, but not a build script, you can add CMake support, but first, contact the upstream and open a PR offering building support. If it's rejected because the author doesn't want any kind of build script, or the project is abandoned, CCI can accept your build script. Take a look at [Bzip2](https://github.com/conan-io/conan-center-index/blob/master/recipes/bzip2/all/CMakeLists.txt) and [DirectShowBaseClasses](https://github.com/conan-io/conan-center-index/blob/master/recipes/directshowbaseclasses/all/CMakeLists.txt) as examples.
-
-### System Packages
-
-> :information_source: For exceptional cases where only system packages can be used and a regular Conan package may result in an incompatible and fragile package, a separated system package may be created. See the [FAQs](../faqs.md#can-i-install-packages-from-the-system-package-manager) for more.
-
-The [SystemPackageTool](https://docs.conan.io/en/latest/reference/conanfile/methods.html#systempackagetool) can easily manage a system package manager (e.g. apt,
-pacman, brew, choco) and install packages which are missing on Conan Center but available for most distributions. It is key to correctly fill in the `cpp_info` for the consumers of a system package to have access to whatever was installed.
-
-As example there is [xorg](https://github.com/conan-io/conan-center-index/blob/master/recipes/xorg/all/conanfile.py). Also, it will require an exception rule for [conan-center hook](https://github.com/conan-io/hooks#conan-center), a [pull request](https://github.com/conan-io/hooks/pulls) should be open to allow it over the KB-H032.
-
 ## Test the recipe locally
 
 ### Hooks

docs/adding_packages/build_and_package.md

@@ -7,7 +7,13 @@ Both methods often use build helpers to build binaries and install them into the
 ## Contents
 
   * [Build Method](#build-method)
-  * [Package](#package)<!-- endToc -->
+  * [Package Method](#package-method)
+  * [Build System Examples](#build-system-examples)
+    * [Header Only](#header-only)
+    * [CMake](#cmake)
+    * [Autotools](#autotools)
+    * [No Upstream Build Scripts](#no-upstream-build-scripts)
+    * [System Packages](#system-packages)<!-- endToc -->
 
 ## Build Method
 
@@ -23,7 +29,7 @@ Both methods often use build helpers to build binaries and install them into the
 
 * These env vars from profile should be honored and properly propagated to underlying build system during the build: `CC`, `CXX`, `CFLAGS`, `CXXFLAGS`, `LDFLAGS`.
 
-## Package
+## Package Method
 
 * CMake config files must be removed (they will be generated for consumers by `cmake_find_package`, `cmake_find_package_multi`, or `CMakeDeps` generators). Use `rmdir(self, os.path.join(self.package_folder, "lib", "cmake"))` or `rm(self, "*.cmake", os.path.join(self.package_folder, "lib"))`.
 
@@ -34,3 +40,41 @@ Both methods often use build helpers to build binaries and install them into the
 * On macOS, install name in `LC_ID_DYLIB` section of shared libs must be `@rpath/<libfilename>`.
 
 * Installed files must not contain absolute paths specific to build machine. Relative paths to other packages is also forbidden since relative paths of dependencies during build may not be the same for consumers. Hardcoded relative paths pointing to a location in the package itself are allowed.
+
+## Build System Examples
+
+The [Conan's documentation](https://docs.conan.io) is always a good place for technical details.
+General patterns about how they can be used for OSS in ConanCenterIndex can be found in the
+[package templates](../package_templates/README.md) sections. These are excellent to copy and start from.
+
+### Header Only
+
+If you are looking for header-only projects, you can take a look on [header-only template](../package_templates/header_only).
+Also, Conan Docs have a section about [how to package header-only libraries](https://docs.conan.io/en/latest/howtos/header_only.html).
+
+### CMake
+
+For C/C++ projects which use CMake for building, you can take a look on [cmake package template](../package_templates/cmake_package).
+
+Another common use case for CMake based projects, both header only and compiled, is _modeling components_ to match the `find_package` and export the correct targets from Conan's generators. A basic examples of this is [cpu_features](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpu_features/all/conanfile.py), a moderate/intermediate example is [cpprestsdk](https://github.com/conan-io/conan-center-index/blob/master/recipes/cpprestsdk/all/conanfile.py), and a very complex example is [OpenCV](https://github.com/conan-io/conan-center-index/blob/master/recipes/opencv/4.x/conanfile.py).
+
+### Autotools
+
+There is an [autotools package template](../package_templates/autotools_package/) amiable to start from.
+
+However, if you need to use autotools for building, you can take a look on [libalsa](https://github.com/conan-io/conan-center-index/blob/master/recipes/libalsa/all/conanfile.py), [kmod](https://github.com/conan-io/conan-center-index/blob/master/recipes/kmod/all/conanfile.py), [libcap](https://github.com/conan-io/conan-center-index/blob/master/recipes/libcap/all/conanfile.py).
+
+Many projects offer [**pkg-config**'s](https://www.freedesktop.org/wiki/Software/pkg-config/) `*.pc` files which need to be modeled using components. A prime example of this is [Wayland](https://github.com/conan-io/conan-center-index/blob/master/recipes/wayland/all/conanfile.py).
+
+### No Upstream Build Scripts
+
+For cases where a project only offers source files, but not a build script, you can add CMake support, but first, contact the upstream and open a PR offering building support. If it's rejected because the author doesn't want any kind of build script, or the project is abandoned, CCI can accept your build script. Take a look at [Bzip2](https://github.com/conan-io/conan-center-index/blob/master/recipes/bzip2/all/CMakeLists.txt) and [DirectShowBaseClasses](https://github.com/conan-io/conan-center-index/blob/master/recipes/directshowbaseclasses/all/CMakeLists.txt) as examples.
+
+### System Packages
+
+> **Note**: For exceptional cases where only system packages can be used and a regular Conan package may result in an incompatible and fragile package, a separated system package may be created. See the [FAQs](../faqs.md#can-i-install-packages-from-the-system-package-manager) for more.
+
+The [SystemPackageTool](https://docs.conan.io/en/latest/reference/conanfile/methods.html#systempackagetool) can easily manage a system package manager (e.g. apt,
+pacman, brew, choco) and install packages which are missing on Conan Center but available for most distributions. It is key to correctly fill in the `cpp_info` for the consumers of a system package to have access to whatever was installed.
+
+As example there is [xorg](https://github.com/conan-io/conan-center-index/blob/master/recipes/xorg/all/conanfile.py). Also, it will require an exception rule for [conan-center hook](https://github.com/conan-io/hooks#conan-center), a [pull request](https://github.com/conan-io/hooks/pulls) should be open to allow it over the KB-H032.

docs/adding_packages/test_packages.md

@@ -29,15 +29,15 @@ Please refer to the [Package Templates](../package_templates/) for the current p
 When using CMake to test a package, the information should be consumed using the
 [`CMakeDeps` generator](https://docs.conan.io/en/latest/reference/conanfile/tools/cmake/cmakedeps.html?highlight=cmakedeps).
 
-This typicall will look like a `CMakeLists.txt` which contain lines similar to
+This typically will look like a `CMakeLists.txt` which contain lines similar to
 
 ```cmake
 find_package(fmt REQUIRED CONFIG)
 # ...
 target_link_libraries(test_ranges PRIVATE fmt::fmt)
 ```
 
-Refere to the [package template](https://github.com/conan-io/conan-center-index/blob/master/docs/package_templates/cmake_package/all/test_package/CMakeLists.txt) for more examples.
+Refer to the [package template](https://github.com/conan-io/conan-center-index/blob/master/docs/package_templates/cmake_package/all/test_package/CMakeLists.txt) for more examples.
 
 > **Notes** It's still important to test targets provided by `cmake_find_package[_multi]` generators.
 > It should help in the migration (and compatibility) with Conan v2. See [v1 test package template](https://github.com/conan-io/conan-center-index/blob/master/docs/package_templates/cmake_package/all/test_v1_package/CMakeLists.txt) for details.

docs/error_knowledge_base.md

@@ -445,7 +445,7 @@ class SomeRecipe(ConanFile):
 
 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](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/cmake/3.x.x/conanfile.py#L104-L105)) which only provide binaries, see [our packing policy](adding_packages/conanfile_attributes.md#settings) for more, should do as follows:
+- @prince-chrismc This needs to a better example; For "tool" recipes ([example](https://github.com/conan-io/conan-center-index/blob/e604534bbe0ef56bdb1f8513b83404eff02aebc8/recipes/cmake/3.x.x/conanfile.py#L104-L105)) which only provide binaries, see [our packaging policy](adding_packages/build_and_package.md) for more, should do as follows:
 
     ```python
         def package_id(self):

docs/faqs.md

@@ -253,7 +253,7 @@ The hook [KB-H032](error_knowledge_base.md#KB-H032) does not allow `system_requi
 system packages at same recipe.
 
 There are exceptions where some projects are closer to system drivers or hardware and packaging as a regular library could result
-in an incompatible Conan package. To deal with those cases, you are allowed to provide an exclusive Conan package which only installs system packages, see the [How-to](adding_packages/README.md#system-packages) for more.
+in an incompatible Conan package. To deal with those cases, you are allowed to provide an exclusive Conan package which only installs system packages, see the [How-to](adding_packages/build_and_package.md#system-packages) for more.
 
 ## Why ConanCenter does **not** build and execute tests in recipes