Merge branch 'develop-cfs-templates' into develop. Close #157.

**Description**

The cFS application generation backend has a fixed template that it uses
to generate the cFS application. That template does not fit all use
cases, so we are finding users heavily modifying the output (which is
hard to keep up with when there are changes), and or not using ogma
altogether for that reason.

Allowing users to pick their own cFS template would make Ogma more
versatile.

**Type**

- Feature: Enable customizing output produced.

**Additional context**

None.

**Requester**

- Ivan Perez.

**Method to check presence of bug**

Not applicable (not a bug).

**Expected result**

Ogma allows users to pick the custom cFS application template they want
to use instead of relying on the one provided by default.

The following dockerfile generates the cFS application using the default
template and using a copy and the default template and checks that both
are the same. It then adds a file to the copy of the template and checks
that the file is copied to the target directory when the custom template
is used, after which it prints the message "Success".

```Dockerfile
FROM ubuntu:trusty

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update

RUN apt-get install --yes software-properties-common
RUN add-apt-repository ppa:hvr/ghc
RUN apt-get update

RUN apt-get install --yes ghc-8.6.5 cabal-install-2.4
RUN apt-get install --yes libz-dev

ENV PATH=/opt/ghc/8.6.5/bin:/opt/cabal/2.4/bin:$PWD/.cabal-sandbox/bin:$PATH

RUN cabal update
RUN cabal v1-sandbox init
RUN cabal v1-install alex happy
RUN apt-get install --yes git

CMD git clone $REPO && \
    cd $NAME && \
    git checkout $COMMIT && \
    cd .. && \
    cabal v1-install $NAME/$PAT**/ --constraint="aeson>=2.0.3.0"                              && \
    cp -r $NAME/ogma-core/templates/copilot-cfs custom-template-cfs                           && \
    find custom-template-cfs -iname '.gitignore' -delete                                      && \
    ./.cabal-sandbox/bin/ogma cfs --variable-file $NAME/ogma-cli/examples/cfs-variables --variable-db $NAME/ogma-cli/examples/cfs-variable-db --app-target-dir original                                   && \
    ./.cabal-sandbox/bin/ogma cfs --variable-file $NAME/ogma-cli/examples/cfs-variables --variable-db $NAME/ogma-cli/examples/cfs-variable-db --app-target-dir new --app-template-dir custom-template-cfs && \
    diff -rq original new                                                                     && \
    rm -rf new                                                                                && \
    echo "Success" >> custom-template-cfs/test                                                && \
    ./.cabal-sandbox/bin/ogma cfs --variable-file $NAME/ogma-cli/examples/cfs-variables --variable-db $NAME/ogma-cli/examples/cfs-variable-db --app-target-dir new --app-template-dir custom-template-cfs && \
    cat new/test
```

Command (substitute variables based on new path after merge):

```sh
$ docker run -e "REPO=https://github.com/NASA/ogma" -e "NAME=ogma" -e PAT="ogma-" -e "COMMIT=<HASH>" -it ogma-verify-157
```

**Solution implemented**

Modify `ogma-core` to use variable expansion based on mustache to create
the output files.

Modify `ogma-core`'s template to use the variables used by the cFS
application generation module.

Modify `ogma-core` to give users the ability to pick a template
directory via an optional input argument.

Modify `ogma-cli` to give users the ability to pick a template directory
via an optional input argument (exposing the corresponding argument from
`ogma-core`).

Modify `README` to demonstrate new capability.

**Further notes**

None.

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