Skip to main content

Getting Started

The easiest way to get started is to use the NS initializer and create a new application. This will expand all the necessary files for the project setup and the NS application. For existing projects there is also a migration guide. It is highly recommended to first read the the documentation about the project setup before migrating.

Important

Make sure to expand the project setup after using the NS initializer, or after making changes to the project model. You can use the /scripts/expand_project_setup.nss script or use the micro radiant to expand.

Default setup​

Each NS project setup requires an expansionSettings.xml. This file is the starting point of each expansion and it is different from the expansionSettings.xml file used by the application. It describes:

  • Where to find the model files.
  • Where to generate the expanded artifacts.
  • Which expansion resources to use, depending on your software projects.

It is also necessary to have a pom.xml file. This is a maven project file that includes the expanders-maven-plugin, which is used to run the expansion. The root of your repository will look like this.

<repository-root>
├── .nsproject/
│   └── expansionSettings.xml
│   └── model/
│       └── projectSetup.xml
├── project/
│   └── ...
├── scripts/
│   └── expand_project_setup.nss
│   └── harvest_project_setup.nss
├── CHANGELOG.md
├── Jenkinsfile
├── pom.xml
.

In the .nsproject directory you can find the expansionSettings.xml file as well as model files and harvest files. The project directory is where all project setup artifacts expanded as well as the usual files and folders you expect from an NS application. This directory can be changed in the expansionSettings.xml. We will take a deeper look on this directory later. Furthermore NS scripts are provided to expand and harvest the project setup.

Configuring the model​

It is recommended to update the model using the micro radiant.

  1. Install the org-normalizedsystems-northstar-project-plugin plugin if you haven't already.
  2. Import a new project in the micro radiant
  3. Select the expansionSettings.xml from the .nsproject directory. (On linux, directories starting with . are often hidden, you can use the checkbox to show hidden files if needed)
  4. Give the project a fitting name. Typically suffixed with -setup or -project-setup to differentiate it from the NS application project in micro radiant.
  5. You can now start editing the model. Using the build plugin you can also expand and harvest the project setup.

Customizations​

The project expanders are fairly prescriptive, but still allow for a lot of customization. Ideally everything is done through the model. The different elements have fields that can be configured and options for special use cases. Many of the expanded files also have custom anchors to allow customization. It is however also possible to add your own files next to the expanded files if you have a use case that is impossible to fit into the model. This is heavily discouraged though.