Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions

ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Documentation

Developer

Adding a new feature to the ISIS software

Home

Introduction

This is a step-by-step guide describing the process for adding a new feature to ISIS. Since ISIS is made up of many application programs, when we say new feature we mean adding a new program to ISIS. Each program in ISIS is focussed on a narrow subject, for example, isis2std is focussed on exporting ISIS cubes to standard image formats such as jpeg, tif, or png.

Many people have contributed code, documentation, answers, and suggestions to the ISIS software. As part of that community you should be familiar with the contributing guide.

ISIS applications are written in C++ and are supported on Ubuntu Linux and Mac OS.

Resources

The ISIS library contains hundreds of support classes and functions. Every application takes advantage of these support routines to accomplish its tasks. We encourage you to get familiar with the library before starting to write your first application.

There are over 400 ISIS applications. We suggest you get familiar with as many of these as possible, so you don't duplicate a feature that has already been implemented, and to use an existing application as a template for your new feature.

ISIS applications are linked against many useful external libraries. We encourage you to become familiar with these external libraries. A list of the external libraries ISIS uses directly can be found in the environment.yml file.

Getting the ISIS source code

All of the ISIS source code is available on GitHub. This GitHub source code repository is the primary Git repository for ISIS. If you are unfamiliar with Git and/or GitHub you should go through the GitHub getting started pages before you start writing code.

Steps to get ISIS source code on your local machine

  1. Setup a GitHub account
  2. Fork the ISIS repository
  3. Clone your fork to a local repository

Setting up an environment to compile and link ISIS

The ISIS package is written in C++. In order to run and test your new feature, you will need to compile the source code and link it against the ISIS library and the external libraries. Follow the instructions on the ISIS GitHub Wiki for building ISIS.

Depending on how your computer is setup, you may also need to install:

Once you have a complete environment set up for ISIS development, we suggest you compile and build all of ISIS. This step will make sure sure you have everything setup and ready to go.

Starting a conversation with other ISIS developers

Before you start writing your new feature, create an issue for it on the ISIS GitHub site. Doing this will allow other ISIS developers to way in on your preposed feature. By posting a description of what you want to do and asking questions, other developers can give you pointers on how to implement it. Label the issue as an "enhancement", to give others an idea what kind of issue it is.

Writing your new application

Creating the files for your new application

The ISIS source code is organized by having a dedicated directory where all of the source code for an application is stored. The files in this directory will be exclusively to your feature. This is where using another application as a template can be very useful.

The source code inside an ISIS application directory should be organized to be a callable ISIS application. This is a change from the older style applications that could not be called directly by other applications. Details about writing callable ISIS applications can be found at: Refactoring ISIS Applications

  1. Decide where your new application belongs
  2. Create a directory using the same name as you new application
  3. Create a "main.cpp" file
  4. Create a "yournewapp.cpp" file
  5. Create a "yournew_app.h" file
  6. Create a "yournewapp.xml" file
  7. Create any additional support files (e.g., Supportclass.cpp, Supportclass.h

Populate the new files with the code necessary to implement your feature.

You may also want to create a test file for your new application, and one for each supporting class you write.

Compile and link your new application for the first time

Since you are adding a new application to ISIS you will need to reconfigure your build with cmake. This will add the new application to the list of applications the build system knows about.

  1. Change your current working directory to the ISIS build directory (cd $ISISROOT)
  2. Remove the CMakeCache.txt file (rm CMakeCache.txt)
  3. Re-run the cmake command (cmake -GNinja ..)
  4. Build the ISIS library and all of the applications (ninja)

Fix, run, hand test, debug the new application

Iterate over the following steps until you have your new feature producing the desired result

  1. Fix any compile or linking errors
  2. Rebuild the ISIS library and your new application (ninja)
  3. Run your application and test the user interface
  4. Run your application and test the output
    1. Cube DN's - Are they what you expect?
    2. Cube labels - Have they been modified as you intend?
    3. History - Did the application add a cube history entry for every output cube?
    4. Original label - If your application is an import program, did it store the original label in the output cube
    5. print.prt file - Did your application write a log entry to the print.prt file?
    6. Cleanup temporary files - If your application used any temporary files, did it remove them before it exited?

Testing for your new application

Applications and complex support classes in ISIS are required to have tests that exercise the majority of the their code. These test are written using googletest (aka, gtest). The source code for all gtests is located in the "isis/tests" directory. Create a new test file for your application with the name "FunctionalTestsYournewapp.cpp", and one for each support class with a descriptive name. Write tests to exercise the application and any support classes. Remember to test only the functionality of your new code and not the ISIS library. Tests for the ISIS library already exist. See the guide for writing tests for detailed instructions.

Change Log and Attributions

Now you need to let the ISIS community know about your new application and add your name to the list of people who have contributed to ISIS over it's lifetime.

Edit the "CHANGELOG.md" file, located at the root of your local repository, and add an entry describing your new application. Read the instructions inside the file carefully.

Edit the ".zenodo.json" file, also located at the root or you local repository, and add your information.

Submit your new application for review

Now that you have all the pieces for your new application and it works perfectly. It's time to get it reviewed by other ISIS developers, so it can be added to ISIS and be distributed with the next public feature release.

  1. Tell git to track your new files (git add new_files)
  2. Commit them to your local repository (git commit -m "brief description")
  3. Push the new application to your GitHub fork (git push origin)
  4. Create a pull request on GitHub
  5. Iterate with the reviewers to fix any issues, resolve and conflicts and explain any questions
  6. Update your pull request with any changes

Once your reviewers are satisfied one of them will merge your new application code with the ISIS dev branch. When the next public feature release is created, your new application will be available alongside the other ISIS applications.

Document History

Stuart Sides2022-03-15Original document