-
Notifications
You must be signed in to change notification settings - Fork 6
Developer HowTo
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.
You need to install the following items:
- A recent Java Development Kit (JDK).
- Eclipse development platform. Pick the standard edition. If you are using a Linux distro that has a good package management system, you can use that to install instead.
- Git plugin -- Usually bundled with Eclipse install.
- Maven plugin -- Usually bundled with Eclipse install.
- CDT plugin, only if you work on the C backend.
- PyDev plugin, only if you work on the Python backend.
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".
- 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.
The first time the app starts on a given host, it installs a set of base models and examples. These are embedded into the app as a zip file, which now needs to be created. Here we assume that at some point you have run a pre-built version of the app, so the files are already present. To create the zip archive, use the command line:
cd ~/n2a/repos
zip ../initialDB base/models/* base/references/* local/models/* local/references/*
Note that some Windows-based zip tools cannot handle Unicode characters in the file names. It is best to create this file using the Unix-based zip program.
Copy the resulting ~/n2a/initialDB.zip file into the source tree at n2a/N2A/src/gov/sandia/n2a/db. In Eclipse, press F5 to refresh the db package.
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.
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.
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
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
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
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