# dtc_rake

Rake tasks for building apps produced by DTC.DEV team.

## Installation

Add this line to your application's `Gemfile`:

```ruby
gem "dtc_rake", git: ""ssh://git@codebase.plus4u.net:9422/dtc.rake.git
```

And then execute:

    $ bundle

Or build it yourself from source as:

    $ git clone ssh://git@codebase.plus4u.net:9422/dtc.rake.git
    $ cd dtc.rake/dtc_rake
    $ rake install

# Quick Start

For a quick start just add to your appbox project's `Rakefile`:

```ruby
require "dtc_rake"

DtcRake.configure do |config|
  config.appbox_uarchive = "<uarchive_path>"
  config.appbox_territory_code = "<territory_code>"
  config.appbox_meta_artifact_code = "<meta_artifact_code>"
  config.appbox_location_code = "<folder_code>"
end
```

*Note: The appbox project name should be `<vendor>_<app>-appbox` and it must contain a uuApp deployment descriptor with default name `<vendor>_<app>-uuapp.json`.*

All shared tasks will be found and loaded automatically, you can verify it with `rake -T` command.

It is recommended to check whether the defaults fit your needs and change the configuration if needed.

Also set `DTC_RAKE_PASSWD` environment variable. It represents path to password file with authentication credentials (necessary for appbox creation and packs uploading). Its value can be either path relative to `uu.home` or an absolute path.

Example:

```sh
rake upload:cmd DTC_RAKE_PASSWD=12-345-6
# or
rake upload:cmd DTC_RAKE_PASSWD=/path/to/12-345-6
```

*Tip: If you set `DTC_RAKE_PASSWD` globally (e.g. in your `.bash_profile` or `.zshenv`), you won't have to set it everytime you use Rake tasks from this gem.*

# Documentation

[Online yardoc](http://www.rubydoc.info/gems/dtc_rake)

## Configuration

The following example shows all configuration options:


```ruby
require "dtc_rake"

DtcRake.configure do |config|
  # Code of application. Guessed from root_dir name if not set.
  config.app = "<app_code>"

  # Code of appbox artifact. Guessed from vendor, app and version in uuApp
  # deployment descriptor if not set.
  config.appbox_artifact_code = "<artifact_code>"

  # Code of appbox location (folder or organization unit). Required.
  config.appbox_location_code = "<folder_code>"

  # Code of appbox meta artifact. Default value: UU.OS/RUNTIME/APP_BOX.
  config.appbox_meta_artifact_code = "<meta_artifact_code>"

  # Code of territory where the appbox artifact is / should be. Required.
  config.appbox_territory_code = "<territory_code>"

  # Path to uarchive with contents of appbox artifact. Default value: nil.
  # If not set, appbox is created with empty content.
  # Relative path is relative to root_dir.
  config.appbox_uarchive = "<uarchive_path>"

  # Path to uuApp deployment descriptor. Guessed from vendor and app if not set.
  config.app_descriptor_path = "<deployment_descriptor_path>"

  # Print messages in colors. Default value: true.
  config.colorize = true

  # Name of folder with build products. Default value: target.
  # Relative path is relative to root_dir.
  config.output_dir = "target"

  # Appbox project root folder. Default value: current working directory.
  config.root_dir = Dir.pwd

  # Upload uuApp deployment descriptor to appbox artifact. Default value: false.
  config.upload_app_descriptor = true

  # Code of vendor. Guessed from root_dir name if not set.
  config.vendor = "<vendor_code>"
end
```

## Explanation of Provided Tasks

### appbox

Creates new appbox artifact.

### build:all

Builds all available packs. Which packs get built depends on which projects exist for the app being built.

Example:

Only tasks for building command client and server would be available for app with the following structure.

```
cds.gb
  +- cds_gb
  +- cds_gb-appbox
     +- Rakefile
  +- cds_gb-cmd
```

### build:cmd

Builds pack with command server. Available if project `<vendor>_<app>-cmd` exists.

### build:dockerfiles

Builds pack with `Dockerfile`s. Available if project `<vendor>_<app>-dockerfiles` exists.

### build:gem

Builds pack with command client Ruby gem. Available if project `<vendor>_<app>` exists.

### build:vuc

Builds pack with visual use cases. Available if project `<vendor>_<app>-vuc` exists.

### build:yardoc

Builds pach with command client yardoc. Available if project `<vendor>_<app>` exists.

### upload:all

Uploads all available packs to appbox artifact. Which packs get uploaded depends on which projects exist for the app being built. See example for the `build:all` task.

### upload:cmd

Uploads pack with command server to appbox artifact. Available if project `<vendor>_<app>-cmd` exists.

Requires `DTC_RAKE_PASSWD` to be set.

### upload:descriptor

Uploads uuApp deployment descriptor to appbox artifact. Available if `config.upload_app_descriptor` is set to `true`.

Requires `DTC_RAKE_PASSWD` to be set.

### upload:dockerfiles

Uploads pack with `Dockerfile`s to appbox artifact. Available if project `<vendor>_<app>-dockerfiles` exists.

Requires `DTC_RAKE_PASSWD` to be set.

### upload:gem

Uploads pack with command client Ruby gem to appbox artifact. Available if project `<vendor>_<app>` exists.

Requires `DTC_RAKE_PASSWD` to be set.

### upload:vuc

Uploads pack with visual use cases to appbox artifact. Available if project `<vendor>_<app>-vuc` exists.

Requires `DTC_RAKE_PASSWD` to be set.

### upload:yardoc

Uploads pach with command client yardoc to appbox artifact. Available if project `<vendor>_<app>` exists.

Requires `DTC_RAKE_PASSWD` to be set.

# How-to

## How to Add Custom Task

When a project requires a specific Rake task then implement it and add it to a shared task as dependency:

```ruby
namespace :build do
  desc "Builds pack with widget"
  task :widget do
    ...
  end
end
task "build:all" => "widget"
```

## How to Remove a Task

If there is a task that doesn't make sense for you then you can exclude it from loading.

For example, to exclude the `upload:dockerfiles`, replace the `require`

```ruby
require "dtc_rake"
```

with

```ruby
require "dtc_rake/tasks"
DtcRake::Tasks.load_tasks(exclude: ["upload_dockerfiles.rake"])
```

To remove check that is used also as dependency for e.g. `upload:all`, it is needed to remove it also from prerequisites of task. Example how to remove `upload:dockerfiles` and do not call it when building all packs.

```ruby
require "dtc_rake/tasks"
DtcRake::Tasks.load_tasks(exclude: ["upload_dockerfiles.rake"])
Rake::Task["upload:all"].prerequisites.delete("dockerfiles")
```

# Development

After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`.