Documentation Request: Integrating External Libraries into F Prime

[elliotfayman]

Integrating External Libraries into F Prime

I’ve been exploring how to integrate external libraries into F Prime by wrapping them in a new passive or active component. However, I haven’t found much documentation on the specifics of this process. I received the following guidance, which outlines two approaches: one for adding .so libraries (to be dynamically linked) and another for adding .a libraries (to be statically linked).

First Approach: Adding a .so (Shared Object) Library

1. Build the external library to generate a .so file, if one is not already available.
2. Copy the generated .so and header files into the F Prime project.
3. Create a new passive or active F Prime component to wrap the semantics of the library.
4. Use mod_deps in the component’s CMake file to establish the necessary link dependencies.
5. Use target_include_directories to configure the header search paths for the compiler.

Second Approach: Adding a .a (Static Archive) Library

1. Build the external library to generate a .a archive file if one is not already available.
2. Copy the generated .a and header files into the F Prime project.
3. Use ExternalProject_Add in CMake to manage the library’s build process within F Prime
4. Update mod_deps and target_include_directories as needed to support static linking and header inclusion.

Additional Notes:

1. In addition to the above guidance, I referenced the following CMake file which integrates an external library in the F Prime reference application: FS/App/PiCamera/CMakeLists.txt at dev · FP-Mission/FS
2. You must cross compile the external library if your target is a different architecture or platform than the one with which you’re building the library.
3. Whether you choose to wrap the external library in a passive or active component depends on the semantics of the external library. For example, if your library is similar to NumPy in Python, you should consider wrapping it inside a passive component because (and this is my impression - feel free to correct) that library does not require its own thread to operate, while reducing the number of active components can help conserve CPU resources.

[thomas-bc]

@elliotfayman thanks for posting this issue. This is indeed a perfect candidate for #2732 and will likely be implemented as such.

[ronaldo-monteiro]

I would like to see the use of AI in code improvements for the project, especially in Python.

[matt392code]

library-integration-guide.md
This documentation:
-Provides clear step-by-step instructions
-Includes practical examples
-Covers both static and dynamic linking
-Addresses cross-compilation
-Includes best practices and troubleshooting

[LeStarch]

Need to document the following starting places:

1. Existing binary library
2. Including an external build
3. Importing/exporting libraries into F Prime build

Note: Should ensure that GNC patterns are respected.

Deliverables:

1. Example
2. Cmake helpers
3. How-To guide

[matt392code]

fprime-lib-integration.md
Proposed comprehensive guide that addresses all three key areas requested:

1. Existing binary library integration
2. Including external builds
3. Importing/exporting libraries into F Prime build

The guide includes:

1. Examples with both code and XML configurations
2. CMake helpers for library detection and cross-platform configuration
3. A detailed how-to guide with best practices and troubleshooting sections

The documentation respects GNC (Guidance, Navigation, and Control) patterns by emphasizing:

• Deterministic behavior
• Proper error handling
• Component lifecycle management
• Resource management