ogma-cli: Allow customizing the cFS application template. Refs #157.

ogma-cli/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Revision history for ogma-cli
 
+## [1.X.Y] - 2024-11-11
+
+* Provide ability to customize template in cfs command (#157).
+
 ## [1.4.1] - 2024-09-21
 
 * Version bump 1.4.1 (#155).

ogma-cli/README.md

@@ -115,9 +115,10 @@ flags to customize the list of known variables, so that projects can maintain
 their own variable databases beyond what Ogma includes by default.
 
 cFS applications are generated using the Ogma command `cfs`, which receives
-three main arguments:
+four main arguments:
 - `--app-target-dir DIR`: location where the cFS application files must be
   stored.
+- `--app-template-dir DIR`: location of the cFS application template to use.
 - `--variable-file FILENAME`: a file containing a list of variables that must
 be made available to the monitor.
 - `--variable-db FILENAME`: a file containing a database of known variables,
@@ -187,6 +188,45 @@ void COPILOT_ProcessIcarousPosition(void)
 }
 ```
 
+### Template Customization
+
+By default, Ogma uses a pre-defined template to generate the cFS monitoring
+application. It's possible to customize the output by providing a directory
+with a set of files with a cFS application template, which Ogma will use
+instead.
+
+To choose this feature, one must call Ogma's `cfs` command with the argument
+`--app-template-dir DIR`, where `DIR` is the path to a directory containing a
+cFS application template. For example, assuming that the directory
+`my_template` contains a custom cFS application template, one can execute:
+
+```
+$ ogma cfs --app-template-dir my_template/ --variable-db examples/cfs-variable-db --variable-file examples/cfs-variables
+```
+
+Ogma will copy the files in that directory to the target path, filling in
+several holes with specific information:
+
+- `{{variablesS}}`: this will be replaced by a list of variable declarations,
+  one for each global variable that holds information read from the cFS
+software bus that must be made accessible to the monitoring code.
+
+- `{{msgSubscriptionsS}}`: this will be replaced by a list of calls to
+  `CFE_SB_Subscribe`, subscribing to the necessary information coming in the
+software bus.
+
+- `{{msgCasesS}}`: this will be replaced by a switch case statements that match
+  the ID of an incoming message, to handle information being received that must
+be updated and would trigger a re-evaluation of the monitors.
+
+- `{{msgHandlerS}}`: this will be replaced by function definitions of the
+  functions that will be called to actually update the variables with
+information coming from the software bus, and re-evaluate the monitors.
+
+We understand that this level of customization may be insufficient for your
+application. If that is the case, feel free to reach out to our team to discuss
+how we could make the template expansion system more versatile.
+
 ## ROS Application Generation
 
 The Robot Operating System (ROS) is a framework to build robot applications.

ogma-cli/src/CLI/CommandCFSApp.hs

@@ -56,9 +56,10 @@ import Command.CFSApp ( ErrorCode, cFSApp )
 
 -- | Options needed to generate the cFS application.
 data CommandOpts = CommandOpts
-  { cFSAppTarget   :: String
-  , cFSAppVarNames :: String
-  , cFSAppVarDB    :: Maybe String
+  { cFSAppTarget      :: String
+  , cFSAppTemplateDir :: Maybe String
+  , cFSAppVarNames    :: String
+  , cFSAppVarDB       :: Maybe String
   }
 
 -- | Create <https://cfs.gsfc.nasa.gov/ NASA core Flight System> (cFS)
@@ -68,7 +69,11 @@ data CommandOpts = CommandOpts
 -- This is just an uncurried version of "Command.CFSApp".
 command :: CommandOpts -> IO (Result ErrorCode)
 command c =
-  cFSApp (cFSAppTarget c) (cFSAppVarNames c) (cFSAppVarDB c)
+  cFSApp
+    (cFSAppTarget c)
+    (cFSAppTemplateDir c)
+    (cFSAppVarNames c)
+    (cFSAppVarDB c)
 
 -- * CLI
 
@@ -87,6 +92,13 @@ commandOptsParser = CommandOpts
         <> value "copilot-cfs-demo"
         <> help strCFSAppDirArgDesc
         )
+  <*> optional
+        ( strOption
+            (  long "app-template-dir"
+            <> metavar "DIR"
+            <> help strCFSAppTemplateDirArgDesc
+            )
+        )
   <*> strOption
         (  long "variable-file"
         <> metavar "FILENAME"
@@ -106,6 +118,11 @@ commandOptsParser = CommandOpts
 strCFSAppDirArgDesc :: String
 strCFSAppDirArgDesc = "Target directory"
 
+-- | Argument template directory to cFS app generation command
+strCFSAppTemplateDirArgDesc :: String
+strCFSAppTemplateDirArgDesc =
+  "Directory holding cFS application source template"
+
 -- | Argument variable list to cFS app generation command
 strCFSAppVarListArgDesc :: String
 strCFSAppVarListArgDesc =

ogma-core/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## [1.X.Y] - 2024-11-13
 
 * Fix incorrect path when using Space ROS humble-2024.10.0 (#158).
+* Use template expansion system to generate cFS monitoring application (#157).
 
 ## [1.4.1] - 2024-09-21
 

ogma-core/ogma-core.cabal

@@ -106,8 +106,12 @@ library
       base                    >= 4.11.0.0 && < 5
     , aeson                   >= 2.0.0.0  && < 2.2
     , bytestring
+    , Cabal                   >= 2.4      && < 3.10
+    , directory               >= 1.3.1.0  && < 1.4
     , filepath
+    , microstache             >= 1.0      && < 1.1
     , mtl
+    , text                    >= 1.2.3.1  && < 2.1
 
     , ogma-extra              >= 1.4.1 && < 1.5
     , ogma-language-c         >= 1.4.1 && < 1.5