= Development
:toc:
:toc-placement!:

The following should get you started on setting up your development environment. As a prerequisite you will need a Ruby 2.2 environment. We
recommend to use https://rvm.io/[RVM] to create an isolated development
environment. On Windows the http://rubyinstaller.org/[RubyInstaller for
Windows] is probably the easiest way to get started. In this case you
will need the http://rubyinstaller.org/add-ons/devkit/[DevKit] as well.

'''
toc::[]
'''

Once you have a working Ruby environment it is time to
https://help.github.com/articles/fork-a-repo/[fork] the repository. Refer to the link:../CONTRIBUTING.adoc[Contributing] guide for more information.

The following sections list the most important commands you will need for
development.

== Setup

* Install http://bundler.io/[Bundler]:
+
....
$ gem install bundler
....
* Install dependencies:
+
....
$ bundle install
....
* Get a list of all available build tasks:
+
....
$ bundle exec rake -T
....

* Build the Landrush gem:
+
....
$ bundle exec rake install
....
* Clean all generated files:
+
....
$ bundle exec rake clean clobber
....

== Tests

* Run the test suite:
+
....
$ bundle exec rake test
....
* Run a single test file:
+
....
$ bundle exec rake test TEST=<path to test file>
....
* Run cucumber/aruba acceptance tests:
+
....
$ bundle exec rake features
....

NOTE: The acceptance tests currently work only for OS X, out of the box.
On Linux, one has to manually configure the host visibility for the
TLD _landrush-acceptance-test_. See *Linux* in the *Visibility on the Host* section of the link:Usage.adoc[Usage guide]. On Windows,
the acceptance tests won't work due to a bug in
https://github.com/cucumber/aruba/issues/387[Aruba].

* Run a single cucumber/aruba acceptance tests:
+
....
$ bundle exec rake features FEATURE=features/<feature-filename>.feature
....

== Documentation

The documentation of this plugin is written in http://asciidoctor.org[Asciidoc]. If you need some syntax help,
refer to the http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference].

To build the documentation you can execute

----
$ bundle exec rake html
----

which will build the HTML documentation into the folder _build/html_.

The source code also contains a link:../Guardfile[Guardfile] for the https://github.com/guard/guard[Guard] library.
You can execute

----
$ bundle exec guard
----

and your HTML documentation will be automatically updated on each change to an Asciidoc source file.
https://github.com/guard/guard-livereload[Live reload] is also enabled, so you just need to install the right
http://livereload.com/extensions/#installing-sections[LiveReload Safari/Chrome/Firefox extension] and your
browser can refresh the page each time you save a change to your Asciidoc files.

== Misc

* Run the vagrant binary with the Landrush plugin loaded from your local
source code:
+
....
bundle exec vagrant landrush <command>
....