Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New developer doc for adding new feature #4859

Merged
merged 3 commits into from
Mar 20, 2022
Merged

New developer doc for adding new feature #4859

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ea6639d
New developer doc for adding new feature
scsides Mar 18, 2022
bb26ab4
Address comments
scsides Mar 19, 2022
3cfb31a
Address a couple comments
scsides Mar 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 187 additions & 0 deletions isis/src/docsys/documents/DeveloperAddFeature/DeveloperAddFeature.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
<?xml version="1.0" encoding="UTF-8"?>
<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://isis.astrogeology.usgs.gov/Schemas/Documentation/documentation.xsd">
<files>
<file>
<body>
<h2><a name="Introduction">Introduction</a></h2>
<p>
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 are referring 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.
</p>
<p>
ISIS applications are written in C++ and are supported on Ubuntu Linux and Mac OS.
</p>

<h2><a name="Resources">Resources</a></h2>
<p>
The <a href="https://isis.astrogeology.usgs.gov/Object/Developer/index.html>ISIS library"</a> contains
scsides marked this conversation as resolved.
Show resolved Hide resolved
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.
</p>
<p>
There are over 400 <a href="https://isis.astrogeology.usgs.gov/Application/index.html"ISIS applications</a>.
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.
</p>
<p>
ISIS applications are linked against many external libraries. We encourage you to become familiar with these
external libraries. One place to start is the environment.yml file located at the root of the ISIS source
scsides marked this conversation as resolved.
Show resolved Hide resolved
code tree.
</p>

<h2><a name="Getting the ISIS source code">Getting the ISIS source code</a></h2>
<p>
All of the ISIS source code is available on <a href="https://github.com/USGS-Astrogeology/ISIS3">GitHub</a>.
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 <a href="https://docs.github.com/en/get-started">getting started</a>
pages before you start writing code.
</p>

<h3>Steps to get ISIS source code on your local machine</h3>
<ol>
<li>Setup a GitHub account</li>
<li>Fork the ISIS repository</li>
<li>Clone your fork to a local repository</li>
</ol>

<h2><a name="Setting up an environment to compile and link ISIS">Setting up an environment to compile and link ISIS</a></h2>
<p>
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
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake"> building ISIS</a>.
</p>
<p>
Depending on how your computer is setup, you may also need to install:
</p>
<ul>
<li> Compiler (Mac OS Xcode, Linux GNU C++)</li>
<li> Editor (Vim, Nano, Atom, ...</li>
</ul>

<p>
Once you have a complete environment set up for ISIS development, we suggest you
<a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#building-isis3">compile and build</a>
all of ISIS. This step will make sure sure you have everything setup and ready to go.
</p>

<h2><a name="Starting a conversation with other ISIS developers">Starting a conversation with other ISIS developers</a></h2>
scsides marked this conversation as resolved.
Show resolved Hide resolved
<p>
Before you start writing your new feature, create an <a href="https://github.com/USGS-Astrogeology/ISIS3">issue</a> 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.
scsides marked this conversation as resolved.
Show resolved Hide resolved
</p>

<h2><a name="Writing your new application">Writing your new application</a></h2>

<h3>Creating the files for your new application</h3>
<p>
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.
</p>
<ol>
<li>Decide where your new application belongs</li>
<li>Create a directory using the same name as you new application</li>
<li>Create a "main.cpp" file</li>
<li>Create a "your_new_app.cpp" file</li>
scsides marked this conversation as resolved.
Show resolved Hide resolved
<li>Create a "your_new_app.xml" file</li>
<li>Create any additional support files (e.g., support_class.cpp, support_class.h</li>
scsides marked this conversation as resolved.
Show resolved Hide resolved
scsides marked this conversation as resolved.
Show resolved Hide resolved
</ol>
<p>
Populate the new files with the code necessary to implement your feature.
scsides marked this conversation as resolved.
Show resolved Hide resolved
</p>

<h3>Compile and link your new application for the first time</h3>
<p>
Since you are adding a new application to ISIS you will need to re-run the cmake command. This will add
scsides marked this conversation as resolved.
Show resolved Hide resolved
the new application to the list of applications the build system knows about.
</p>
<ol>
<li>Change you current working directory to the ISIS build directory (cd $ISISROOT)</li>
<li>Remove the contents of the build directory (rm -rf *)</li>
scsides marked this conversation as resolved.
Show resolved Hide resolved
<li>Re-run the cmake command (cmake -GNinja ..)</li>
<li>Build the ISIS library and all of the applications (ninja)</li>
</ol>

<h3>Fix, run, hand test, debug the new application</h3>
<p>
Iterate over the following steps until you have your new feature producing the desired result
</p>
<ol>
<li>Fix any compile or linking errors</li>
<li>Rebuild the ISIS library and your new application (ninja)</li>
<li>Run your application and test the user interface</li>
<li>Run your application and test the output</li>
<ol>
<li>Cube DNs</li>
<li>Cube labels</li>
<li>History</li>
<li>Original label</li>
<li>print.prt file</li>
<li>Cleanup any temporary files</li>
scsides marked this conversation as resolved.
Show resolved Hide resolved
</ol>
</ol>

<h2><a name="Writing your new application">Writing your new application</a></h2>
scsides marked this conversation as resolved.
Show resolved Hide resolved
Applications in ISIS are required to have tests that exercise the majority of the application specific code.
These test are written using Google Test (aka, gtest). The source code for all gtests is located in the "isis/tests" directory
scsides marked this conversation as resolved.
Show resolved Hide resolved
starting at the root of the code repository. Create a new file for your new application with the name "FunctionalTestsYournewapp.cpp", and
write tests to exercise the application. Remember to test only the functionality of your new code and not the ISIS library. Tests for the
ISIS library already exist.
scsides marked this conversation as resolved.
Show resolved Hide resolved
</p>

<h2><a name="Submit your new application for review">Submit your new application for review</a></h2>
<p>
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.
</p>
<ol>
<li>Tell git to track your new files (git add new_files)</li>
scsides marked this conversation as resolved.
Show resolved Hide resolved
<li>Commit them to your local repository (git commit -m "brief description")</li>
<li>Push the new application to your GitHub fork (git push origin)</li>
<li>Create a pull request on <a href="https://github.com/USGS-Astrogeology/ISIS3/compare">GitHub</a></li>
<li>Iterate with the reviewers to fix any issues, resolve and confilcts and explain any questions</li>
<li>Update your pull request with any changes</li>
</ol>
<p>
Once your reviewers are satisfied one of them will merge your new application code with the ISIS dev brand. When
scsides marked this conversation as resolved.
Show resolved Hide resolved
the next public feature release is created, your new application will be available alongside the other ISIS applications.
</p>

</body>

<type>HTML</type>

<source>
<filename>DeveloperAddFeature.html</filename>
</source>
</file>
</files>

<category>
<categoryItem>guide</categoryItem>
</category>

<audience>
<target>developer</target>
</audience>

<bibliography>
<title>Developer </title>
<brief>Adding a new feature to the ISIS software</brief>
<description>
This is a step-by-step guide describing the process for adding a new feature to ISIS.
</description>
<author>Stuart Sides</author>
<date>2022-03-15</date>
</bibliography>

<history>
<change date="2022-03-15" name="Stuart Sides">Original document</change>
</history>
</documentation>