# 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"
```

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install dtc_rake

# Quick Start

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

```ruby
require "dtc_rake"

DtcRake.configure do |config|
  config.product_code = "<product_code>"
  config.product_name = "<product_name>"
  config.appbox_territory_code = "<territory_code>"
  config.appbox_location_code = "<folder_code>"
end
```

*Note: The appbox project name should be `<vendor>_<app>-appbox`. If not, you must specify `config.vendor` and `config.app` within `DtcRake.configure` in `Rakefile`.*

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. Since 0.2.0.
  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>"
  
  # Appbox version. Read from VERSION file located in the same directory
  # as Rakefile if not set.
  config.appbox_version = "1.2.3-dev"

  # 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"

  # Code of product the appbox belongs to. Required.
  config.product_code = "UU-CLOUDG01-C3"

  # Name of product the appbox belongs to. Required.
  config.product_name = "uuCloudg01C3"

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

  # Upload README.md or README.txt to appbox artifact. Default value: false.
  config.upload_readme = true

  # Upload uuCloud deployment descriptor to appbox artifact. Default value: false.
  config.upload_uucloud_descriptor = true

  # Path to uuCloud deployment descriptor. Default value: uucloud_descriptor.json.
  config.uucloud_descriptor_path = "<uucloud_descriptor_path>"

  # Code of vendor. Guessed from root_dir name if not set.
  config.vendor = "<vendor_code>"
  
  # List of files (or glob patterns) determining which files get updated by
  # version:sync task. Default: none.
  config.version_sync_files = ["../uu_c3/lib/uu_c3/version.rb"]
end
```

`VERSION` file contents example:

```
1.2.3-dev
```

*Note: Leading and trailing whitespace (incl. line breaks) does not matter - it gets stripped/trimmed. Only the version itself is important.*

### Environment Variables

Configuration can also be specified in environment variables. Environment variables take precedence over configuration in `Rakefile`.

```
  DTC_RAKE_APP=<app_code>
  DTC_RAKE_APPBOX_ARTIFACT_CODE=<artifact_code>
  DTC_RAKE_APPBOX_LOCATION_CODE=<folder_code>
  DTC_RAKE_APPBOX_META_ARTIFACT_CODE=<meta_artifact_code>
  DTC_RAKE_APPBOX_TERRITORY_CODE=<territory_code>
  DTC_RAKE_APPBOX_UARCHIVE=<uarchive_path>
  DTC_RAKE_APPBOX_VERSION=1.2.3-dev
  DTC_RAKE_COLORIZE=false
  DTC_RAKE_OUTPUT_DIR=target
  DTC_RAKE_PRODUCT_CODE=UU-CLOUDG01-C3
  DTC_RAKE_PRODUCT_NAME=uuCloudg01C3
  DTC_RAKE_ROOT_DIR=<root_dir>
  DTC_RAKE_UPLOAD_README=true
  DTC_RAKE_UPLOAD_UUCLOUD_DESCRIPTOR=true
  DTC_RAKE_UUCLOUD_DESCRIPTOR_PATH=<uucloud_descriptor_path>
  DTC_RAKE_VENDOR=<vendor_code>
```

## 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 `docker` 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 pack 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_uucloud_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 `docker` 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 pack with command client yardoc to appbox artifact. Available if project `<vendor>_<app>` exists.

Requires `DTC_RAKE_PASSWD` to be set.

### version

Shows the current version stored in `VERSION` file located in the same directory as `Rakefile`.

### version:bump:major

Bumps the major version. Updates `VERSION` file located in the same directory as `Rakefile` and files specified in `config.version_files`.

### version:bump:minor

Bumps the minor version. Updates `VERSION` file located in the same directory as `Rakefile` and files specified in `config.version_files`.

### version:bump:patch

Bumps the patch version. Updates `VERSION` file located in the same directory as `Rakefile` and files specified in `config.version_files`.

### version:set

Sets the version. The version may contain *prerelease* and/or *build metadata* parts (see [Semantic Versioning](http://semver.org)). Updates `VERSION` file located in the same directory as `Rakefile` and files specified in `config.version_files`.

# 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"])
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`.