Developer HowTo - sandialabs/n2a GitHub Wiki

We are very excited that you want to contribute to this effort! It is people like you that make projects like this successful.

Your first task is to prepare an environment on your computer where you can edit and run the program from source code. Those instructions appear in another section below.

Your second task is to offer back the changes that you make. As with most open source projects, there are two ways to do this. Initially, you can offer changes via pull requests on github. We will commit the code to the repository for you. If you make a lot of contributions, you will be invited to join the project as a full member. This will enable you to commit changes directly.

Keep in mind that code contributed to the project must be free from intellectual property encumbrances. That means that there are no patent issues, that you have not copied it from someone else's work, and that you give the project full permission to publish it under any license.

Setting up a development environment

You need to install the following items:

After you set up Eclipse, prepare a workspace with the source code. The following instructions are merely one way to do this. (If you know Eclipse well enough to have a different preference, then you don't need these instructions!)

  • Clone the repository by following the instructions on the Source page. This step requires a working set of git tools on your system. In the following, this source directory will be called "n2a". This repository contains submodules, so use the "--recurse-submodules" command-line option or equivalent.
  • Start Eclipse
  • Create a new workspace in the cloned directory (n2a).
  • Click File > Import
  • Click General > Existing Projects into Workspace
  • Select root directory n2a
  • The N2A project should be check-marked. Plugin projects may also be check-marked. Click Finish.
  • In Windows:Preferences:General:Content Types, select "Java Source File" and set Default Encoding to "UTF-8".

The language parser files must be generated before Eclipse can build the project. Right-click on pom.xml and select Run As > Maven generate-sources.

To launch N2A, right-click on gov.sandia.n2a.Main.java and select Run As > Java Application. A new run configuration will be created, which can be subsequently accessed via the green play button in the toolbar.

Building the distribution JAR

To construct the jar, right-click on pom.xml and select Run As > Maven build. Enter "package" as the goal. The resulting jar will appear in n2a/N2A/target/N2A-{version}.jar.

Coding Style

Any new code should follow our preferred Java formatting style. To prepare Eclipse:

  • Select Window > Preferences > Java > Code Style > Formatter
  • Import n2a/style-java.xml (and accept it as the style)

If you work on the C Backend, then follow similar steps under C/C++ to import n2a/style-cpp.xml

External Resources

LEMS/NeuroML

The LEMS backend uses XML schema files (.xsd) from the LEMS and NeuroML distributions to determine order during export. Copies of the relevant files are included in this repository. These may be optionally updated following the instructions in gov/sandia/n2a/backend/neuroml/ExportNeuroML.java

Spreadsheet Input

The C backend can read Microsoft Excel files. It depends on two external software packages: miniz and pugixml. Copies of the relevant files are included in this repository. These may be optionally updated following the instructions in gov/sandia/n2a/backend/vensim/runtime/spreadsheet.tcc

OpenGL

The C backend supports 3D graphics via OpenGL. This requires several header files from the Khronos Group. Copies of the relevant files are included in this repository. These may be optionally updated following the instructions in gov/sandia/n2a/backend/c/runtime/holder.h