Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

Costas Zarifis


Tutorials, code snippets, hacks and turtles... A lot of turtles... Heh.

FORWARD Unit Development - Getting Started Guide

In this post, I will describe how to set up all the tools required to start developing FORWARD Units. For the development of the FORWARD units we will be using the very widely used IDE WebStorm.

If you're using a Mac or Windows, the installation should be pretty straight forward, just head over to this page, download the appropriate installer and just run it. For instructions on how to install WebStorm on linux follow this link.

Take into account that WebStorm is not a Freeware so you might have to pay for a license. However, if you are affiliated with a University you can get a free activation code! All you have to do is apply for one here. Make sure you use a valid university email when applying.

While you are implementing the unit, you'll have to test it to make sure that your code is not just correct but efficient as well. For this, we will be using Karma tests. Karma requires NodeJS to be installed on your system so click on this link to install Node, npm and bower. If you don't already have them installed take care of that first and then return to this post.

OK! At this point I'm assuming that you have successfully installed both WebStorm and NodeJS (with the corresponding package managers npm and bower).

Next step is to get access to the repository with the part of the FORWARD codebase that is required to develop and test your units. Contact us if you wish to contribute to the project so that we can grant you access to the git repository.

As soon as you gain access feel free to clone the repository and start working on your unit. Run the following command to clone the repo (make sure you replace the "git_repository_url" with the actual url of the repo)

git clone git_repository_url fw_unit_development

The next step is to install all the dependencies that are required by FORWARD and the testing framework, run the following commands:

cd fw_unit_development
npm install
bower install

If something goes wrong make sure that you've successfully installed npm and bower.

These commands will use config files that include all the necessary dependencies and they will install everything for you. It might take a while, so be patient.

If everything went smoothly so far, you probably have all the required libraries installed on your system.

Let's set up WebStorm!

Firstly, launch WebStorm and select the option "open",

Browse to the directory containing the project you just cloned from the repository:

and click OK.

We will be using Chrome to run the Karma tests, so if you don't have it installed you should follow this link and install it.

This is a good point to reboot your machine, so do that and come back to this post.

OK, now re-launch WebStorm.

When WebStorm reloads it will open the project that you were working on before you closed it, which should have the codebase you cloned from git (if that's not the case just open the correct project).

When the project loads, you should be seeing something like this:

On the top right corner you should be seeing the option "All Tests", if this option is not visible click on the drop down menu and select that option. The next step is to click the green "play" button to run the tests.

As soon as you do that a new chrome window will pop up, and Karma will get initialized:

Probably the first time you attempt to run the tests, Karma will fail due to a minor issue with socket.io.

If you get an error message like the following:

Don't panic! Follow this link to take care of that issue and come back here.

Additionally, Mac users have reported the following error:

ERROR [karma]: { [Error: EMFILE: too many open files ... 

The reason why you might be getting this error is that Mac computers have a very low limit on the number of open processes that could be launched from a particular user. So since Node needs to access multiple files, it ends up spawning multiple processes to achieve the reads, so that's why you are getting this error. The fix is rather simple, just follow the instructions in his link and it should fix the problem. Note that you have to reboot in order for the changes to take effect.

At this point you've probably taken care of all the issues so you should be able to run all the existing tests. Just run the "All Tests" option like you did before, wait for the Chrome window to pop up and Karma will run the tests.

Congrats! You're now ready to build your own units!

Have a look at the existing units under the directory:

src/main/js/units

Also, have a look at the existing tests for each unit:

src/test/js/units

Aaaand we're done! Happy coding!


About the author

Costas Zarifis


Discussions

comments powered by Disqus