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.

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.

The root of your repository will look like this.

<repository-root>
├── .nsproject/
│   ├── expansionSettings.xml
│   └── model/
│       ├── ...
│       └── projectSetup.xml
├── applications/
├── components/
├── conf/
├── docker/
├── expansions/
├── scripts/
│   ├── ...
│   └── rejuvenate_nsproject_setup.nss
├── .cleanExclude
├── .gitignore
├── CHANGELOG.md
├── Jenkinsfile
├── pom.xml
.

Compared to a setup without the project-expanders you now have an .nsproject directory in which you can find the expansionSettings.xml file as well as model files and harvest files. The rest of the repository looks quite normal with the difference that some files are expanded. These files always have an expander comment at the top. Also note the existence of the rejuvenate_nsproject_setup.nss script which is used to harvest and expand the project setup.

.cleanExclude

The .cleanExclude file is extremely important. It makes sure that non-expanded files are not cleaned/deleted when performing a clean expand.

Viewing and configuring the model​

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

Micro Radiant version

Since micro radiant 4.5 it is possible to have multiple expansionSettings files within the same micro radiant project. It is recommended to use at least this version when using the project-expanders.

  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 root directory of your project. You should see two expansionSettings files found (.nsproject and conf/expansionSettings).
  4. Give the project a fitting name.
  5. Switch between expansionSettings files using the project facet in the left column.
  6. You can now start editing the model.

More info about importing projects in micro radiant can be found here.

Git​

Unlike other expanded files, files expanded by the project setup expanders are, and should be, included within git. This makes it easier when switching branches and also facilitates a simpler 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.

Since the expanded files are checked into git, it is also possible to just edit the files even outside of custom anchors. This is discouraged as it will impact the evolvability of your project-setup negatively, but it is useful in cases where the project-expanders don't provide a solution yet.