hgk Tooling
1. Overview
The hgk command line tooling comes as part of HELIX Groundkit, and allows you to:
-
Create Groundkit model elements such as Component Types and Deployment Types, and generate the resources needed to implement them.
-
Generate documentation for a model element or an entire Workspace.
-
Build and run Component Type unit tests.
-
Build a Mission, which produces a JAR file for each Deployment and a Mission Database.
-
Manage Workspaces and Bundles.
2. Using hgk
hgk is self-documenting. To bring up the help menu and show the available commands, open up a terminal and run hgk --help or hgk -h.
Usage: hgk [-h | --help] [SUB-COMMAND] [SUB-COMMAND-ARGS]
Helix Groundkit is a development kit for spacecraft ground software
Command arguments:
--help, -h : display this help menu
--version : display version information
Available sub-commands:
board : Generate resources for boards
bundle : Commands for managing bundles
component-type : Create, delete and generate code for component types
deployment-type : Create and generate documentation for deployment types
mission : Create, generate, and build missions and their documentation
module : Create, delete and generate code for modules
osal : Generate resources for osals
python : Generate python data bindings for a given mission
service : Create, delete and generate code for services
workspace : Create, delete and manipulate workspaces and bundles
The -h flag can also be added to any sub-command to see the required and optional arguments. For example, hgk component-type create -h:
usage: hgk component-type create
[-h] [--verbose] [--root ROOT] name
Create a new component-type
positional arguments:
name name of the component-type
named arguments:
-h, --help show this help message and exit
--verbose display a verbose output message for the command
(default: false)
--root ROOT root workspace path, required if not currently
within a workspace
While using hgk, it is expected that commands are run from within a Workspace, however it’s possible to run commands from outside a Workspace if the --root flag is specified.
To run commands with more expressive output to the console, use the --verbose flag.
2.1. hgk Version
The version of the tooling can be checked with the following command:
hgk --version
|
Note that this command does NOT return the Groundkit version; this version refers only to the |
The version of the tooling the Workspace expects to use is specified as a dependency in the workspace.xml file. Using a different tooling version in a Workspace to the one specified can lead to issues reading the model.
|
It is important to update each Workspace's tooling dependency inside the |
2.2. Documentation and Tutorials
The full Groundkit documentation can be opened in your default browser with the following command:
hgk-open-docs
To generate the tutorials, run:
hgk-prepare-tutorials
This creates the necessary Workspaces and resources needed to follow the tutorials in the current directory.
3. Creating Model Elements
New model elements can be created with the command:
hgk <ElementType> create <ElementName>
where <ElementType> is the type of element you want to create (e.g. Component Type), and <ElementName> is a name of your choosing. The following model elements can be created this way:
-
Boards
-
Component Types
-
Deployment Types
-
Missions
-
Services
-
Modules
-
OSALs
This will create a blank XML template in the Workspace's library directory, or missions directory in the case of Missions. It is also possible to create a new Workspace this way, using hgk workspace create <workspace-name>.
4. Generating Model Elements
Once a model element has been created and its template XML file has been written, it can then be generated.
This process involves generating all the relevant resources needed to implement the artefact to satisfy the XML model. This includes generating the necessary directory structures, skeleton implementation code for the model element, and the glue code from the GenOne:Java language implementation that handles its interfaces. hgk generate produces these resources for Component Types, Services, Missions, and Modules, leaving the implementation code to be written.
Model elements can be generated with the command:
hgk <ElementType> generate <ElementName>
where <ElementType> is the artefact you want to generate (e.g. Component Type), and <ElementName> is the name of the artefact. The following model elements can be generated this way:
-
Component Types
-
Missions
-
Services
-
Modules
-
OSALs
|
The |
5. Generating Documentation
hgk can be used to generate documentation for model elements and entire Workspaces. This is in both HTML and Markdown form, and will be created in the output directory unless otherwise specified.
hgk <ElementType> generate-docs <ElementName>
where <ElementType> is the model element such as component-type or mission and <ElementName> is its name.
By default, this will also generate documentation for any target dependencies, although this can be changed by specifying --no-deps.
The tooling uses the XML model to populate this documentation. This includes using the <Description> and <Documentation> XML tags, as well as denoting the structure of the artefact.
6. Missions
As well as creating, generating, and generating documentation for Missions, hgk can build a Mission. Building produces the outputs needed to run the software.
Specifically, the build command creates a JAR file for each Deployment in the mission.xml, and a Mission Database. The Mission Database archives the Mission and its dependencies, and ground software such as HELIX Lab reads it to command and monitor the deployed software.
A Mission can be built using the following command:
hgk mission build <MissionName:MAJOR.MINOR.PATCH>
If no version number is specified, there must only be a single version of the Mission within the Workspace and its Bundle dependencies. The artefacts built with this command will be created in the output directory.
7. Using Workspaces and Bundles
The hgk bundle command allows a user to manage Groundkit Bundles.
|
Bundles cannot be created or required in a Workspace with this command. Use the |
7.1. Install and Uninstall Bundles
A Bundle is a snapshot of a Workspace, which enables teams to share library elements. Bundles on the disk must be installed to make them available to use in Workspaces.
hgk bundle install <path-to-bundle-archive>
They can also be uninstalled when they are no longer needed:
hgk bundle uninstall <BundleName>
This command can be forced using the -f flag.
7.4. Preparing a Workspace
hgk workspace prepare prepares a Workspace so it is ready to be used for development. This checks that the structures are valid and updates local resources in the Workspace.
7.5. Requiring a Bundle
Requiring a Bundle in a Workspace brings in all of the Bundle's elements, allowing them to be used.
hgk workspace bundle require <BundleName>
Unless the Bundle version is specified, hgk will bring in the latest installed version.
|
After a new Bundle requirement has been added, the Workspace must be prepared again using |
8. Unit Tests
The hgk component-type build command allows a user to build and run Component Type unit tests. For example, hgk component-type build <ComponentName>.
Each test in the ComponentNameImplTest.java file will output a success or fail status to the console. There will also be a summary of the overall test results.
By specifying the --build-only flag, the tests will not run.
|
Refer to the Unit Testing tutorial for more information about performing unit tests in Groundkit. |
9. Python
Groundkit can be used to generate a Python API for a Mission, enabling it to be interacted with via Python scripts. This takes a Mission Database and generates a set of classes representing each of the model elements within the Mission to a specified output directory. To do this, run:
hgk python generate <MissionName:MAJOR.MINOR.PATCH> -m <path-to-missiondb> -o <output-directory>
-
The positional argument names the Mission and its version, using the Mission's full name. The version can be omitted where only one version of that Mission is available.
-
-mis the path to the Mission Database to generate from. -
-ois the directory to generate into.
10. Related Documentation
-
Getting Started: Getting Started
-
Tutorial: Unit Testing