Add subtopology generation with fprime-util new --subtopologies (#203)

.github/actions/spelling/expect.txt

@@ -1,3 +1,4 @@
+aei
 argc
 atoi
 bak
@@ -148,6 +149,7 @@ memset
 metadata
 mkdir
 mkdtemp
+mosa
 mstarch
 mul
 MULTILINE
@@ -252,6 +254,7 @@ toctree
 todo
 toolchain
 toolchains
+TOPOLOGYCONFIG
 TOPOLOGYDEFS
 truediv
 typehints

docs/conf.py

@@ -3,6 +3,7 @@
 Documentation:
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
+
 # pylint: disable=invalid-name
 
 import re

src/fprime/common/models/serialize/array_type.py

@@ -3,6 +3,7 @@
 Created on May 29, 2020
 @author: jishii
 """
+
 from fprime.util.string_util import format_string_template
 
 from . import serializable_type
@@ -95,9 +96,11 @@ def to_jsonable(self):
             "type": self.__class__.__name__,
             "size": self.LENGTH,
             "format": self.FORMAT,
-            "values": None
-            if self._val is None
-            else [member.to_jsonable() for member in self._val],
+            "values": (
+                None
+                if self._val is None
+                else [member.to_jsonable() for member in self._val]
+            ),
         }
 
     def serialize(self):

src/fprime/common/models/serialize/bool_type.py

@@ -2,6 +2,7 @@
 Created on Dec 18, 2014
 @author: tcanham, reder
 """
+
 import struct
 
 from .type_base import ValueType

src/fprime/common/models/serialize/enum_type.py

@@ -2,6 +2,7 @@
 Created on Dec 18, 2014
 @author: tcanham, reder
 """
+
 import struct
 
 from .type_base import DictionaryType

src/fprime/common/models/serialize/numerical_types.py

@@ -6,6 +6,7 @@
 
 @author mstarch
 """
+
 import abc
 import struct
 

src/fprime/common/models/serialize/serializable_type.py

@@ -4,6 +4,7 @@
 @author: tcanham
 
 """
+
 from fprime.util.string_util import format_string_template
 
 from . import array_type

src/fprime/common/models/serialize/string_type.py

@@ -4,6 +4,7 @@
 @author: tcanham
 
 """
+
 import struct
 
 from fprime.constants import DATA_ENCODING

src/fprime/constants.py

@@ -1,6 +1,7 @@
 """
 Provided constants for use within the fprime system.
 """
+
 # pylint: disable=W0105
 """
 In order to transmit data in a serialized format, string objects need to be encoded. Otherwise,

src/fprime/cookiecutter_templates/cookiecutter-fprime-project/hooks/post_gen_project.py

@@ -9,6 +9,7 @@
 
 @author thomas-bc
 """
+
 import subprocess
 import sys
 import requests

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/cookiecutter.json

@@ -0,0 +1,9 @@
+{
+    "subtopology_name": "MySubtopology",
+    "subtopology_desc": "My Subtopology Description",
+    "__subtopology_name_upper": "{{cookiecutter.subtopology_name.upper()}}",
+    "__prompts__": {
+        "subtopology_name": "Subtopology name",
+        "subtopology_desc": "Subtopology description"
+    }
+}

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/hooks/pre_gen_project.py

@@ -0,0 +1,8 @@
+from fprime.util.cookiecutter_wrapper import is_valid_name
+
+name = "{{ cookiecutter.subtopology_name }}"
+
+if is_valid_name(name) != "valid":
+    raise ValueError(
+        f"Unacceptable subtopology name: {name}. Do not use spaces or special characters"
+    )

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/{{cookiecutter.subtopology_name}}/CMakeLists.txt

@@ -0,0 +1,12 @@
+set(SOURCE_FILES
+    "${CMAKE_CURRENT_LIST_DIR}/{{cookiecutter.subtopology_name}}.fpp"
+    "${CMAKE_CURRENT_LIST_DIR}/intentionally-empty.cpp"
+)
+
+register_fprime_module()
+
+set_target_properties(
+    ${FPRIME_CURRENT_MODULE}
+    PROPERTIES
+    SOURCES "${CMAKE_CURRENT_LIST_DIR}/intentionally-empty.cpp"
+)

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/{{cookiecutter.subtopology_name}}/TODO.md

@@ -0,0 +1,27 @@
+# {{cookiecutter.subtopology_name}} - F' Subtopology
+
+The starter files for the subtopology have been generated. To fully integrate it into your project, you need to do the following steps:
+
+1. Add the `{{cookiecutter.subtopology_name}}/` folder to its parent directory's `.cmake (or CMakeLists)` file if not already there:
+
+```cmake
+add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/{{cookiecutter.subtopology_name}}/")
+```
+
+2. Create a directory in the root of your project called `SubtopologyConfigs`. This will include the config files for your subtopologies. Move `{{cookiecutter.subtopology_name}}Config.fpp` into `SubtopologyConfigs`. Create a CMakeLists.txt file in the folder, and include the config file as a source file:
+
+```cmake
+# in SubtopologyConfigs/CMakeLists.txt
+
+set(SOURCE_FILES
+    ...
+  "${CMAKE_CURRENT_LIST_DIR}/{{cookiecutter.subtopology_name}}Config.fpp"
+    ...
+)
+
+register_fprime_module()
+```
+
+3. Lastly, add `add_fprime_subdirectory("${CMAKE_CURRENT_LIST_DIR}/SubtopologyConfigs/")` to your `project.cmake` folder.
+
+In the future, you only need to add the config file to your source list. The directory setup should be a one-time event.

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/{{cookiecutter.subtopology_name}}/docs/sdd.md

@@ -0,0 +1,56 @@
+# Subtopology `{{cookiecutter.subtopology_name}}`
+
+{{cookiecutter.subtopology_desc}}
+
+> Utilizes the [F Prime Subtopology autocoder](https://github.com/mosa11aei/fprime-subtopology-tool).
+
+## Related Diagrams
+Add any related diagrams here
+
+## Requirements
+Add requirements in the chart below
+| Name | Description | Validation |
+|---|---|---|
+|---|---|---|
+
+## Instantiation
+
+```
+# TODO: EDIT THIS
+
+topology Inst {}
+@<! is topology {{cookiecutter.subtopology_name}} base id 0xAAAA with {
+@<! # fill in as appropriate    
+@<! }
+```
+
+## Redefine-able Instances
+| Instance name | Component |
+|---|---|
+|---|---|
+
+## Subtopology Interface
+
+**Input interface instance**: `module.NameOfInputInterface`
+**Output interface instance**: `module.NameOfOutputInterface`
+
+### Input Interface
+
+Going into `{{cookiecutter.subtopology_name}}`.
+
+| Input port | Output port pair | Type      |
+| ---------- | ---------------- | --------- |
+| clock      | clock_in         | Svc.Sched |
+
+### Output Interface
+
+Going out of `{{cookiecutter.subtopology_name}}`.
+
+| Output port | Input port pair  | Type      |
+| ----------- | ---------------- | --------- |
+| clock_out   | clock            | Svc.Sched |
+
+## Change Log
+| Date | Description |
+|---|---|
+|---| Initial Draft |

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/{{cookiecutter.subtopology_name}}/intentionally-empty.cpp

@@ -0,0 +1,7 @@
+/*
+This file is meant to be intentionally empty. Please do NOT delete this file.
+
+This file is included in the CMakeLists build source files, so that this subtopology can build
+on its own. This is in response to a bug with naming in the autocoded files, and may not be
+necessary in the future.
+*/

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/{{cookiecutter.subtopology_name}}/{{cookiecutter.subtopology_name}}.fpp

@@ -0,0 +1,31 @@
+module {{cookiecutter.subtopology_name}} {
+    # include any instance definitions here. For example:
+    # instance framer: Svc.Framer base id {{cookiecutter.subtopology_name}}Config.{{cookiecutter.subtopology_name}}_BASE_ID + << OFFSET >>
+
+    # note that subtopologies are written with phases, which means inline c++ within this fpp file.
+    # here is an example:
+    # instance myCoolComponent: Components.CoolComponent base id {{cookiecutter.subtopology_name}}Config.{{cookiecutter.subtopology_name}}_BASE_ID + << OFFSET >> \
+    #   queue size {{cookiecutter.subtopology_name}}Config.Defaults.QUEUE_SIZE \
+    #   stack size {{cookiecutter.subtopology_name}}Config.Defaults.STACK_SIZE \
+    #   priority {{cookiecutter.subtopology_name}}Config.Priorities.CoolComponent \
+    #   {
+    #       phase Fpp.ToCpp.Phases.configComponents """
+    #       {
+    #           # some configuration function calls as necessary
+    #       }
+    #       """
+    #   }
+
+    @ {{cookiecutter.subtopology_desc}}
+    topology {{cookiecutter.subtopology_name}} {
+
+        # include any instance declarations here
+        # and wiring connections as well. For example:
+
+        # instance framer
+        # connections Framer {
+        #     ...    
+        # }
+
+    } # end topology
+} # end {{cookiecutter.subtopology_name}}

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/{{cookiecutter.subtopology_name}}/{{cookiecutter.subtopology_name}}Config.fpp

@@ -0,0 +1,23 @@
+module {{cookiecutter.subtopology_name}}Config {
+    # Base ID for your subtopology. All instantiated components will be offsets of this
+    constant {{cookiecutter.subtopology_name}}_BASE_ID = << FILL THIS IN >>
+
+    # include default Queue and Stack sizes here
+    module Defaults {
+        constant QUEUE_SIZE = 10
+        constant STACK_SIZE = 64 * 1024
+    }
+
+    # Priorities for active components should be included in a module like so:
+    # module Priorities {
+    #     const instanceName = 100
+    #     ...
+    # }
+
+    # Custom ports in your subtopology can be defined like so:
+    # port customPort (
+    #     ...
+    # )
+
+    # Any other constants can go here as well that configure your subtopology
+}

src/fprime/cookiecutter_templates/cookiecutter-fprime-subtopology/{{cookiecutter.subtopology_name}}/{{cookiecutter.subtopology_name}}TopologyDefs.hpp

@@ -0,0 +1,30 @@
+#ifndef {{cookiecutter.__subtopology_name_upper}}_DEFS_HPP
+#define {{cookiecutter.__subtopology_name_upper}}_DEFS_HPP
+
+namespace {{cookiecutter.subtopology_name}} {
+    struct {{cookiecutter.subtopology_name}}State {
+        /* include any variables that are needed for 
+        configuring/starting/tearing down the topology */
+    };
+    struct TopologyState {
+        {{cookiecutter.subtopology_name}}State {{cookiecutter.subtopology_name}}_state;
+    };
+}
+
+namespace GlobalDefs {
+    namespace PingEntries {
+        /* include any ping entries that are needed for the subtopology
+        e.g., rate groups need FAIL and WARN ping enums
+        For example:
+
+        namespace {{cookiecutter.subtopology_name}}_rateGroup {
+            enum {
+                WARN = 3,
+                FATAL = 5
+            };
+        }
+        */
+    }
+}
+
+#endif

src/fprime/fbuild/builder.py

@@ -2,6 +2,7 @@
 Supplies high-level build functions to the greater fprime helper CLI. This maps from user command space to the specific
 build system handler underneath.
 """
+
 import os
 import re
 from pathlib import Path

src/fprime/fbuild/cli.py

@@ -5,6 +5,7 @@
 
 @author mstarch
 """
+
 import argparse
 from pathlib import Path
 from typing import Callable, Dict, List, Tuple

src/fprime/fbuild/cmake.py

@@ -7,6 +7,7 @@
 
 @author mstarch
 """
+
 # Get a cache directory for building CMakeList file, if need and remove at exit
 import collections
 import copy

src/fprime/fbuild/gcovr.py

@@ -1,4 +1,5 @@
 """ fprime.fbuild.gcovr: coverage target implementations """
+
 import itertools
 import shutil
 import subprocess

src/fprime/fbuild/settings.py

@@ -6,6 +6,7 @@
 
 @author mstarch
 """
+
 import configparser
 import os
 import sys

src/fprime/fbuild/target.py

@@ -5,6 +5,7 @@
 
 @author lestarch
 """
+
 import functools
 import itertools
 from abc import ABC, abstractmethod

src/fprime/fbuild/target_definitions.py

@@ -4,6 +4,7 @@
 as such, each target need only be instantiated but need not be assigned to anything.
 
 """
+
 from .gcovr import GcovrTarget
 from .target import BuildSystemTarget, TargetScope
 from .types import BuildType

src/fprime/fpp/common.py

@@ -4,6 +4,7 @@
 
 @author mstarch
 """
+
 import itertools
 import subprocess
 from pathlib import Path

src/fprime/fpp/impl.py

@@ -5,7 +5,6 @@
 @author thomas-bc
 """
 
-
 import argparse
 import os
 import tempfile