Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add AC pre-processor pattern to docs #2808

Merged
merged 4 commits into from
Jul 31, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/actions/spelling/expect.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1009,6 +1009,9 @@
subpage
subseconds
subtargets
subtopology
Subtopology

Check warning on line 1013 in .github/actions/spelling/expect.txt

View workflow job for this annotation

GitHub Actions / Spell checking

`Subtopology` is ignored by check spelling because another more general variant is also in expect. (ignored-expect-variant)
Subtopologies

Check warning on line 1014 in .github/actions/spelling/expect.txt

View workflow job for this annotation

GitHub Actions / Spell checking

`Subtopologies` is ignored by check spelling because another more general variant is also in expect. (ignored-expect-variant)
suppr
suseconds
SVCLOGFILE
Expand Down
31 changes: 30 additions & 1 deletion docs/UsersGuide/dev/autocoder-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -319,4 +319,33 @@ essential to remember that in this case that file only exists during the build o
the project. Thus, these autocoders should make all decisions on the filename only and not the contents of the file.

Usually, it is a good idea to have the source autocoder provide all dependencies, and have the secondary autocoder set
no additional dependencies. The secondary autocoder is simple input to output.
no additional dependencies. The secondary autocoder is simple input to output.

## Implementing a Pre-Processor Autocoder

In the above steps, a general "build step" autocoder is created, which is when the autocoder is *registered* at the generate (`fprime-util generate`) step, but is executed in the build (`fprime-util build`) step. With recent minor modifications to F Prime's CMake, it is now possible to add an autocoder as a pre-processor. A "pre-processor" autocoder is one that is able to generate model files (fpp) or any other files that can be ingested by F Prime through the native autocoders. An example of this is the [Subtopology Autocoder Tool](https://github.com/fprime-community/fprime-subtopology-tool), which takes annotated fpp files and generates new subtopology model files.

In this case, instead of using `add_custom_command`, you can execute any tools and external scripts using `execute_process`. For example:

```cmake
# example derived from https://github.com/fprime-community/fprime-subtopology-tool

execute_process(
COMMAND ${PYTHON} ${PYTHON_TOOL} --locs ${CMAKE_BINARY_DIR}/locs.fpp --file ${AC_INPUT_FILE} --p ${OUTPUT_FILE} --c ${LOCAL_CACHE}
RESULT_VARIABLE RETURN_CODE
)
```

The `RETURN_CODE` variable is useful to determine whether the script that was being executed returned a non-zero status code. In the case of the example, it is used to determine whether files were generated for the module. Generated files need to be specified by the autocoder, as defined earlier in this documentation. However, one can also specify *removed sources* in the autocoder. This is useful so that a file can be replaced in a module's source list (i.e., an annotated input fpp file is replaced with an autogenerated file with no annotations). That can be done by appending to the `AUTOCODER_REMOVED_SOURCES` list:

```cmake
set(AUTOCODER_REMOVED_SOURCES <files> PARENT_SCOPE)
```

Lastly, you can have your autocoder execute before all other autocoders with the new `PREPEND` argument for `register_fprime_build_autocoder`. Again, deriving from the tool example above:

```cmake
register_fprime_build_autocoder("${CMAKE_CURRENT_LIST_DIR}/fprime-subtopology-tool/src/cmake/autocoder/subtopology.cmake" ON)
```

If the `PREPEND` argument is set to "ON", then the provided autocoder will execute before all other internal autocoders. If set to "OFF", it will do the standard behavior of the function, which is to append the autocoder to the list of all autocoders in the system.
Loading