###Running Gulp

[Gulp](http://gulpjs.com/) is a build program written in JavaScript and running on Node. You will be using Gulp to build JS code for concatenating files, linting those files, minifying code, running tests, and performing other tasks. Please give a look to Gulp's [simple API](https://github.com/gulpjs/gulp/tree/master/docs) before starting.

####0. Overview: how this thing works

(This is a high-level overview. Specific Gulp commands are covered in later sections.)

The recommended usage for Gulp is to have it continuously 'watching' your scripts as you code. When you update a file, Gulp will notice the change and rebuild your code immediately to a target directory.

Depending on which flags you use to start watching the codebase, Gulp will also lint and test your code before building. If there are any failures or problems with your code, Gulp will notify you. All code needs to pass all tests and the linter in order for it to be ready for production. Failing code *must not* be committed to the repo.

Each JS project is considered to be an `app`. An app is a Backbone or Chaplin file that lives in the `/js/apps` directory. So, for example, the `accounting` app is `/js/apps/accounting.js`. It is basically your `main` file, from which all your app's code will be included.

When in default development mode, Gulp will write out to a target directory, usually in OA or Workstation codebase, though you can set the target to be anywhere. (This directory layout is covered in the next section.) These development files should be committed to Github, though they will not be used in production, only development mode.

When you are ready to push code to production you must specifically build the code with the `gulp deploy` command. Again, this will be covered below.


####1. Directory layout

Gulp will be writing your JS files to a target directory. In other words, none of the files in the frontend repo will be served by a web server directly, and must be served in another codebase. If you are developing JS for Orchard's workstation, for example, the target directory will be  `/your_workstation_repo/public/releases`.

A typical directory layout might look something like this:

```bash
- /frontend
- /target_repo
    - /public
        +/dev
        +/releases
```

In the above example, as you develop in the `frontend` directory, your code will be written to, for example, the `/target_repo/public/dev` directory. When you are ready to push a release, it will be written to `/taregt_repo/public/releases`.

####2. Configuration

To set the target path, you need to change the JSON /configs/config.json file to include an *absolute* path to your codebase. The target directory must exist for you to write to the directory. Gulp will not create the directory for you and will throw an error if the directory does not exist.

A sample config file might look like this:

```json
{
    "app": "accounting", //the name of your app. Node '.js' needed
    "path" : "/Users/jmenick/Sites/orchard" // this is the *root* of your orchard codebase
}
```

Several things to keep in mind:

* You can override the app and path values on the command line by using the --app and --path options.
* OA and ALW both use `/public/js/dev` and `/public/js/releases` for development and production code, respectively. Gulp will add these values to your path.

####3. Start Gulp

Now you are ready to get started. First, check your configuration by running:

```bash
$ gulp setup
```

If everything works, you should see something like this:

```bash
[gulp] gulp version mismatch:
[gulp] Running gulp is 3.4.0
[gulp] Local gulp (installed in gulpfile dir) is 3.3.4
[gulp] Using file /Users/jmenick/Sites/orchard/frontend/gulpfile.js
[gulp] Working directory changed to /Users/jmenick/Sites/orchard/frontend
[gulp] Running 'setup'...
[gulp] Finished 'setup' in 191 μs
```

Now you can start gulp:

```bash
$ gulp
```

This will start the watcher. As you begin coding, keep the Terminal window open in the background or on another screen. Whenever you save a file, gulp will lint and rebuild your files on the fly. This should take more than a few millisecond.


####4. Available gulp commands

You can override the config settings for `app` and `target` by using the `--app` and `--target` flags.

```bash
$ gulp --app accounting --target alw
```

If you would prefer not to use watching, you can build your production code with:

```bash
$ gulp build
```

####5. Running tests

TK

####6. Deploying Code

TK