09_development.asc #3

== Development Guide

=== Basic Development Set Up

Helix Web Services runs on Unix-like machines only, typically Linux or OS X.
If you want to use Windows, you will likely need to find an alternative for unicorn.
Please understand that Windows is currently not tested or supported.

Obtain a copy of the source code from the Perforce Workshop.
You can preview the source at https://swarm.workshop.perforce.com/projects/perforce-software-helix-web-services.
If you have an account, you can import the code from `//guest/perforce_software/helix-web-services/main/...` into your workspace.

From there you will need:

1. A recent version of Ruby, Ruby 2.2+ from link:https://rvm.io/[RVM] is recommended.

2. link:http://bundler.io/[Bundler], typically installed via `gem install bundler`.

First, you'll setup a p4d instance locally that's been seeded with some test data.

----
cd helix_web_services_client
bundle install
bundle exec p4util start
bundle exec p4util init
cd ..
----

(You can shut this server down with the command `bundle exec p4util kill` when you're done.)

Next, you'll launch Helix Web Services running under Unicorn, via the Foreman command:

----
cd helix_web_services
bundle install
WORKSPACE_DIR=/tmp/clients bundle exec foreman start
----

In case you need methods that generate temporary client workspaces, you'll need the environment variable set.
If you don't set it, it will likely go to a default directory you do not

This should launch the application in the foreground.
Use `CTRL+C` to kill it.
This mechanism does not automatically reload all changes.

Helix Web Services is a fairly simple Sinatra Rack application.
It's entirely possible to launch it via a debugger under a different application server.
This is typically done in IDEs such as RubyMine.
Use the `config.ru` file in the `helix_web_services` directory and set the `WORKSPACE_DIR` environment variable.


==== Running some tests

Executing tests like we do for automated builds is easy:

----
rake test
----

But, this is probably not what you want.
This will create HTML output files.
And it will start up both p4d and unicorn, then shut them both down.

For your development system, you probably want to have this environment:

1. The web server is running in a debugger
2. The p4d instance is hanging around
3. You can launch client or server tests independently

Since I'm a RubyMine user, steps 1 and 3 are done via the IDE.
Step 2, however, is done by a basic utility function called `p4util`, which I'll describe in the next section.

Setting up RubyMine to runthe webserver requires these steps:

1. Create a new "Rack" configuration, and set the config file to `helix_web_services/config.ru`.
2. Change the port to 9000.
3. Set the `WORKSPACE_DIR` environment variable to something writable like `/tmp/workspaces`.

Setting up RubyMine to launch tests is similarly straightforward:

1. Create a new "RSpec" configuration
2. Set the specs folder to `helix_web_services_client/spec` or `helix_web_services/spec`

===== Setting up a test p4d locally with p4util

The complete calling sequence to reset a test p4d locally is to run these commands in the root if the source tree:

----
p4util kill
rm -rf /tmp/p4util/p4droot
p4util start
p4util init data/p4init
----

I typically execute this sequence in my bash shell using the `&&` operator:

----
p4util kill && rm -rf /tmp/p4util/p4droot && p4util start && p4util init data/p4init
----

This will reset.


==== Using the hws_console against a development mode server

An `hws_console` application is available for local use, which can be useful for trying out a few commands.
Launch it under bundler:

----
cd helix_web_services
bundle exec ./bin/hws_console
----

This will create a basic PRY interactive console.

To create a client instance, you will typically run:

[source,ruby]
----
c = HelixWebServicesClient.new(url: 'http://localhost:9000', user: 'jdoe', password: 'johndoe1A!')
----

From there, `c` is a client instance, you can use to run commands.

[source,ruby]
----
# Print the list of depot names as a string
c.depots.map(&:name).join(", ")
----


==== Adding custom logic to your HWS installation

Some custom logic can be used to add or modify functionality of HWS.
The `CUSTOM_SCRIPTS` property - see <<system_configuration>> - points to a directory.
If this directory exists, any ruby files will be required after most of the core application has been installed.
This is a way to include _some_ logic into the HWS system.

Here's an example custom Ruby script adding methods to HWS via a new Sinatra module:

[source,ruby]
----
require 'sinatra/base'

class MyApp < Sinatra::Base

	get '/my_app' do
		{'custom': true}.to_json
	end
end

HelixWebServices::Master.register_app(MyApp)
----