Nano Bricks

Visual editor for DNA bricks.

Installing and building the project

If you're just interested in trying the software, please see the software overview and try the hosted version at molsys.net/bricks/try. If you're interested in developing or contributing to the software, read on:

Installing

Recommended installation:

1. Install VirtualBox and Vagrant.
2. Clone the repository into a directory on your computer, using git.
3. Change to that directory and run vagrant up; Vagrant will automatically download and configure a virtual machine and install all dependencies for the project.
4. Once the machine has been booted successfully (you will see a message from Vagrant), run vagrant ssh; this will drop you into an SSH shell on the virtual machine
5. Change directories (within the virtual machine) to /vagrant by running cd /vagrant. This folder will automatically mirror the main nano-bricks folder on your host machine.
6. Build the project by running grunt; this will start a task that will automatically rebuild the files in dist whenever you change them.
7. Open the development version by launching dev.html from a web browser on your host machine.

Note: make sure to perform all git operations from your host machine, rather than in the VM (use a separate terminal window)---both because git is much slower in the VM and because the commit authorship will look very weird and you may have trouble pushing changes to GitHub.

More complicated local installation:

Only do this if you have a good reason to; you won't be able to do things like build the documentation or run tests unless you install the required dependencies manually; see bootstrap.sh for details; these are the commands that are run on the VM to install dependencies there.

1. Install Node.js v0.10.x.
2. Clone the repository into a directory on your computer
3. Change to that directory and run npm install to install all dependencies.
4. Globally install grunt with npm install -g grunt
5. Build the project by running grunt; this will start a task that will automatically rebuild the files in dist whenever you change them.
6. Open the development version by launching dev.html from a web browser on your host machine.

Development notes

Nanobricks is written mostly in Coffeescript; it uses the CommonJS module pattern (for the most part) and npm to manage CommonJS packages. Browserify is used to build npm packages for the browser. bower manages non-CommonJS packages, which are included client-side using <script> tags. Dependencies are therefore listed in package.json (for CommonJS packages) and in bower.json (for non-CommonJS packages).

The grunt commands listed below take care of this whole process.

Building the project

The project can be built in two modes: development and release. The development mode is optimized for quick rebuilds, while the release mode condenses everything into one Javascript file and one CSS file.

• To build the development version, simply use grunt; this spawns a task that will watch for changes to the source files and write the results to the dist folder. You can run the project by opening dev.html.
• To build the release version, run grunt build. This is a one-time task and will do a few other things, using usemin to concatenate JS and CSS files together into dist/build.js and dist/build.css, respectively. To bundle a release, run grunt release-interactive and follow the instructions; this will update package.json, bower.json, and generate a tag in git.

Building the documentation

Documentation is generated by JSDuck. JSDuck is installed automatically in the "Recommended installation" method above, otherwise you need to install it yourself. To build the docs, just run grunt docs in the root directory of the project.

Running unit tests

Unit tests are written using Mocha. Mocha is installed automatically in the "Recommended installation" method above, otherwise you need to install it yourself. To build the docs, just run mocha in the root directory of the project.

Contributing

We follow something like the git flow branching model. Make all changes to a topic branch off the branch dev. Merge the topic branch into dev first (preferably using --no-ff) and ensure everything works. Code is only merged into master for release builds, as described above. Semantic versioning is used to describe release versions; this is done automatically by grunt release-interactive. We do not currently have "release" branches, but we probably should. Hotfixes should be developed and tested in a separate branch off master, and a new release should be generated immediately after the hotfix is merged.