CMake documentation refactor (#3981)

* CMake documentation refactor

* sp

* Update cmake-implementations.md

Author: LeStarch

cmake/docs/sdd.md

@@ -2,27 +2,20 @@
 
 F´ leverages CMake as its underlying build system, adding an [API layer](../../reference/api/cmake/API.md) for ease of use.
 
-Since this F´ CMake system is designed to follow CMake norms, certain caveats must be understood before beginning to use CMake. These are described below:
-
-1. CMake should not be used in tandem with the original make system.  If it is needed to switch
-between make systems, perform a `git clean -xdf` command or otherwise remove **all** generated files.
-2. CMake in-source builds are dangerous. Use CMake out-of-source builds.
-
-
 Installation guides for CMake can be found here: [https://cmake.org/install/](https://cmake.org/install/).
 
 A Basic CMake tutorial can be found here: [https://cmake.org/cmake/help/latest/guide/tutorial/index.html](https://cmake.org/cmake/help/latest/guide/tutorial/index.html).
 Although fprime tries to simplify CMake usage for fprime-specific tasks, an understanding of basic CMake is useful.
 
 ## Getting Started with CMake and F´
 
-CMake as a system auto-generates OS-specific make files for building F´. Once these file are generated, standard make tools can be run to perform the compiling, assembling, linking, etc. In other words, CMake is a high-level build system that defers low-level build systems to build. It generates the inputs to these low-level systems in a straightforward way.
+CMake as a system auto-generates OS-specific build files for building F´. Once these files are generated, standard build tools can be run to perform the compiling, assembling, linking, etc. In other words, CMake is a high-level build system that defers low-level build systems to build. It generates the inputs to these low-level systems in a straightforward way.
 
-fprime sets up CMake in such a way that adding a module (component, port, deployment) is easy and automatically takes
+F´ sets up CMake in such a way that adding a module (component, port, deployment) is easy and automatically takes
 advantage of the autocoding capabilities of fprime. To add new modules to the CMake system, users need to perform the following steps:
 
 1. Define a `CMakeLists.txt` file to define the module's source files and dependencies
-2. Ensure that `register_fprime_module` or `register_fprime_executable` is called in that `CMakeLists.txt`
+2. Ensure that `register_fprime_module` or `register_fprime_deployment` is called in that `CMakeLists.txt`
 3. Make sure this new directory defining the `CMakeLists.txt` is added to the deployment `CMakeLists.txt` using
    `add_fprime_subdirectory`.
 
@@ -33,22 +26,14 @@ steps can be found in [API](./cmake-api.md). This document will explain the usag
 
 The CMakeList.txt file defines the steps needed to build **something** in CMake.  In fprime, we use this file to define the source, autocoder, and module dependencies for modules in fprime. A `register_` function is called to tie into the fprime autocoder environment. This keeps fprime modules simple, although all of CMake's power can be used when needed.
 
-Users need only set the `SOURCE_FILES` variable to a list of autocoder and code sources and then call
-`register_fprime_module` to setup a module for fprime (Port/Component). Deployments are done similarly, but since these
-`CMakeLists.txt` files are the entry point to a build, more setup is needed. Deployments should also call
-`register_fprime_executable` as a binary output is desired. `add_fprime_subdirectory` is also used in deployments to
-link to all the other modules they use.
+Users need only set the `AUTOCODER_INPUTS` and `SOURCES` directives to a list of autocoder and code sources as part of the
+`register_fprime_module` call to setup a module for fprime (Port/Component). Deployments are done similarly but use the
+`register_fprime_deployment` call instead.
 
 `add_fprime_subdirectory`, `register_fprime_module`, `register_fprime_executable` docs are here: [API](./cmake-api.md).
 
-A template module `CMakeLists.txt` is documented: [module-CMakeLists.txt-template.md](../../../cmake/module-CMakeLists.txt.template)
-Remember it should be renamed to `CMakeLists.txt` in your module's folder.
-
-A template deployment `CMakeLists.txt` is documented: [deployment-CMakeLists.txt-template.md](../../../cmake/deployment-CMakeLists.txt.template).
-Remember it should be renamed to `CMakeLists.txt` in your deployments folder.
 
-When building a module, ensure it at least calls `register_fprime_module`. Deployments may call
-`register_fprime_executable` in the deployment `CMakeLists.txt` or in any child (usually Top/CMakeLists.txt).
+When defining a module, ensure it at least calls `register_fprime_module`, or `register_fprime_deployment`.
 
 When building a module, remember to add it to the deployment by adding a line `add_fprime_subdirectory(path/module/dir)`
 to the deployment `CMakeLists.txt`.

docs/user-manual/build-system/01-cmake-intro.md

@@ -11,43 +11,25 @@ cannot be found herein.
 ## Build F Prime Utilities
 
 Adding a utility executable that depends on F prime code is easy. Just perform a standard call to
-`register_fprime_executable`. Care should be taken to set the variable `EXECUTABLE_NAME` before
-making this call in order to set the utility's name. This executable will then be output as part
-of the deployment's build. A separate tools deployment may be used to build only utilities.
+`register_fprime_executable`. Care should be taken to set the executable name as the first argument to that
+call. This executable will then be output as part of the deployment's build and may be built directly by name.
+A separate tools deployment may be used to build only utilities.
 
 See: [API](cmake-api.md)
 
 ## Custom Build-System Commands (Make Targets)
 
 Custom build targets that need to be built against modules and global targets can be generated
-using the hook pattern. This pattern involves creating a file with two functions - `add_global_target` and `add_module_target`. These functions are called to add targets to the top level and each module respectively.
+using the hook pattern. This pattern involves creating a file with three functions - `<target>_add_global_target`, `<target>_add_module_target`, and `<target>_add_deployment_target`. These functions are called to add targets to the top level and each module respectively.
 Then this file is registered with `register_fprime_target`.
 
-In the two add functions, the user is expected to call the `add_custom_target` CMake command in order to compose the target itself. **Note:** the user may simply call this function directly to
-add targets that don't have both per-module and global steps.
+These functions can have any code the target needs, but typically uses `add_custom_target` to register the actual target.
 
 See:
   - [add_custom_target](https://cmake.org/cmake/help/latest/command/add_custom_target.html) to view
 information on CMake targets.
   - [API](cmake-api.md) for the syntax of the register call
   - [Targets](cmake-targets.md) for information on the built-in targets
-  - [F´ standard targets](https://github.com/nasa/fprime/tree/devel/cmake/target) as an example of adding targets
-
-**Example (Raw Global Target):**
-
-```
-add_custom_target(
-            dict
-            COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_BINARY_DIR}/dict/serializable ${CMAKE_SOURCE_DIR}/py_dict/serializable
-            COMMAND ${CMAKE_COMMAND} -E touch ${CMAKE_SOURCE_DIR}/py_dict/serializable/__init__.py
-        )
-```
-**Running Example:**
-
-```
-cmake ../Ref
-make dict
-```
 
 ## Custom External Libraries With Other Build Systems
 
@@ -60,7 +42,5 @@ dependency, and `add_custom_command` is used when the system needs access to the
 Alternatively, `ExternalProject_Add` can be used if the external library requires download,
 version control, and building steps.
 
-**Supporting Documentation:**
-1. [https://cmake.org/cmake/help/latest/command/add_custom_target.html](https://cmake.org/cmake/help/latest/command/add_custom_target.html)
-2. [https://cmake.org/cmake/help/latest/command/add_custom_command.html](https://cmake.org/cmake/help/latest/command/add_custom_command.html)
-3. [https://cmake.org/cmake/help/latest/module/ExternalProject.html](https://cmake.org/cmake/help/latest/module/ExternalProject.html)
+For a guide on integrating with another build system see:
+[How To: Integrate External Libraries](../../how-to/integrate-external-libraries.md).

docs/user-manual/build-system/cmake-advanced.md

@@ -1,33 +1,43 @@
-# Package Implementations
+# CMake Implementations
 
 Certain parts of F´ have different implementations that a project may choose from.  The canonical example of this is a file system implementation. Projects may wish to use the stubbed implementation of the file system, the platform supplied standard implementation, or something project-specific like a flash chip or SD card.
 
 These packages must be fully specified. Thus, every platform must specify a specific implementation for every package. These specific implementations may be overridden for a specific executable deployment or unit test.
 
 ## Requiring an Implementation
 
-Modules that require an implementation should call the CMake API function `require_fprime_implementation()` to declare a requirement on a specific implementation. For example, the Os module `require_fprime_implementation(Os/Task)` declares that some implementation of `Os/Task` is required.
+Modules that require an implementation should use the directive `REQUIRES_IMPLEMENTATIONS` in the `register_fprime_module` call.
 
 > [!NOTE]
-> Only `Os` requires an implementation of `Os/Task` as users of the `Os` package get the implementation through `Os` and should not specify it directly.
+> `REQUIRES_IMPLEMENTATIONS` is only needed for modules that have a direct dependency on the implementation, not on their dependents.
 
 ## Choosing an Implementation
 
 Platform developers *must* specify an implementation of every package used in the system. Failing to do so means that a given functionality is undefined and impossible to link.  Stub implementations are provided in the case that a platform does not support a given package's functionality.
 
-Choosing an implementation is done with a series of `choose_fprime_implementation` calls. One for each required implementation defined in the system.  These calls are put in a platform CMake file.
+Choosing an implementation is done with the `CHOOSES_IMPLEMENTATIONS` directive available to `register_fprime_config`. Platform developers should choose implementations as part of the platform definition.
+
+https://github.com/nasa/fprime/blob/dfaf496263bdfff04461179eb99fb3f906a10009/cmake/platform/Linux.cmake#L15-L17
 
 ## Overriding an Implementation Choice
 
-Some executables, unit tests, and deployments may wish to use a different implementation than that specified by the platform. This can be done by a `choose_fprime_implementation` call in the deployment, executable, or unit test's module. For example, a unit test may wish to choose `Os_File_Stub` as an implementation of `Os_File` to disable platform file system support for the given unit test.
+Executables, unit tests, and deployments may wish to use a different implementation than that specified by the platform. This can be done by using `CHOOSES_IMPLEMENTATIONS` directive call in the deployment, executable, or unit test's registration. For example, a unit test may wish to choose `Os_File_Stub` as an implementation of `Os_File` to disable platform file system support for the given unit test:
+
+```
+register_fprime_ut(
+    ...
+  CHOOSES_IMPLEMENTATIONS
+    Os_File_Stub
+)
+```
 
 > [!NOTE]
 > A CMake target with the name of the chosen implementor *must* be defined somewhere in F´, an F´ library used by the project, or by the project itself.
 
 ## Defining an Implementation
 
-To define an implementation, developers should declare an F´ module (using `register_fprime_module`) that implements the needed interface of the package.  Then call `register_fprime_implementation` to specify this module is an implementation.
+To define an implementation, developers should declare an F´ module (using `register_fprime_module`) that implements the needed interface of the package and supply the `IMPLEMENTS` directive to that call.
 
 ## Conclusion
 
-F´ provides for various implementations for certain packages needed by the framework.  See `cmake/API` and `Os` for API descriptions and Os implementations.
+F´ provides for various implementations for certain packages needed by the framework.

docs/user-manual/build-system/cmake-customization.md

@@ -1,12 +1,11 @@
 # F´ and CMake Platforms
 
 Users can create platform-specific build files for the purposes of tailoring fprime
-for given platform targets. Any CMake toolchain file should work, but it will require a platform file created here to add target-specific configuration using the name "${CMAKE_SYSTEM_NAME}.cmake".
+for given platform targets. Any CMake toolchain file should work, but it will require a platform file created here to add target-specific configuration using the name "${FPRIME_PLATFORM}.cmake".
 
-At minimum, this file can be blank, but more commonly there are included paths for "StandardTypes.hpp" to support.
-Build flags and other includes can be added in to support different compile-time options. In addition, these files can define CMake option flags specific to the build.
+Platforms should register a configuration module using `register_fprime_config` that sets the `AUTOCODER_INPUTS`, `HEADERS` and
+`CHOOSES_IMPLEMENTATIONS` directives.
 
-In order to create a new platform from scratch, the user can copy "platform.cmake.template" and fill it out to generate the new platform file. It will guide the user through the setup of this piece.
-
-To understand the platform template: [Platform Template File](https://github.com/nasa/fprime/blob/docs/auto-documentation/docs/UsersGuide/api/cmake/platform/platform-template.md)
-To use the template: [fprime Platform Template](https://github.com/nasa/fprime/blob/devel/cmake/platform/platform.cmake.template)
+`AUTOCODER_INPUTS`: must include one .fpp file defining the platform's [platform types](../../reference/numerical-types.md#platform-configured-types)
+`HEADERS`: lists the `PlatformTypes.h` header defining `PlatformPointerCastType`
+`CHOOSES_IMPLEMENTATIONS`: lists all implementations chosen for the current platform. See: [CMake Implementations](./cmake-implementations.md).

…/build-system/package-implementations.md …al/build-system/cmake-implementations.mddocs/user-manual/build-system/package-implementations.md renamed to docs/user-manual/build-system/cmake-implementations.md docs/user-manual/build-system/package-implementations.md renamed to docs/user-manual/build-system/cmake-implementations.md

@@ -8,9 +8,6 @@ and have it available to the build system.
 
 Targets are applied both at the global scope and per-module scope. Thus each target can provide a set of build targets (one per registered module) and a global build target. For example, a counting target might provide a `count` global target to count all files, and a `<MODULE>_count` to count the files of a given module.
 
-For projects generating GNU make files, these targets can be executed with the `make <target>` and
-`make <MODULE>_<target>` commands. i.e. `make Svc_CmdDispatcher_coverage`.
-
 ## Built-In Targets
 
 The CMake system supplies several targets that are useful for all projects and thus are included