|===\  (==== ===== /===\
|    ) |--     |   |-=-|
|===/  (====   |   |   |

---- Shell build and deploy
     system foundation.

Synopsis
--------
Managing an application is executing commands, tasks are highly specific to
individual applications. Deta supports you in instantly creating tasks in
plain shell script. No extra abstraction layers where you don't need them but
a small tool for launching the tasks, a handful of reusable functions and a
sane configuration management.

Copyright & License
-------------------
Deta is Copyright (c) 2011 David Persson if not otherwise stated.
The code is distributed under the terms of the MIT License. For
the full license text see the LICENSE file.

Requirements
-----------------------
The BASH (Bourne-Again SHell) is required. Deta is continously
tested with recent BASH versions on Linux and Darwin.

Installation
------------
It is suggested to install deta on a per-project basis.

Clone the repository or extract a downloaded archive, then move
or copy the resulting directory to /project/lib/deta.

Change to the `deta` directory and run make, preferrably with a prefix:
```
$ cd /project/lib/deta
$ PREFIX=/project make install
```

This will link the deta tool into the `bin` directory in your project's
root directory and copy the default development configuraton into
a `config/deta` directory. Thus making the deta tool available as:
```
$ cd /project/bin
$ ./deta.sh -c ../config/deta
```

Other setups are possible too but than installation must be performed manually.
You can remove the tool (but keep the configuration) by running:
```
$ cd /project/lib/deta
$ PREFIX=/project make uninstall
```

Quickstart
----------
1. Start to edit a new task.
   ```
   $ $EDITOR deploy.sh
   ```

2. Source the g11n and transfer modules and require a THIS role.
   ```
   source $DETA/g11n.sh
   source $DETA/transfer.sh

   role THIS
   # ...
   ```

3. Our task will clone the project into a temporary directory and recompile
   all MO files. After the task has finished we want the temporary directory
   to be deleted.
   ```
   # ...
   TMP=$(mktemp -d -t deta.XXX)
   defer rm -r $TMP

   download $THIS_REPO $TMP
   cd $TMP

   g11n_compile_mo app/locale
   # ...
   ```

4. Run the tasks through the deta tool.
   ```
   $ ./deta.sh deploy.sh
   ```

Example Tasks
-------------
You can find ready-to-use tasks in the "contrib" subdirectory.

Shell Environment Variables
---------------------------
There are some environment variables that affect the way deta behaves.

DETA_COMPRESSOR_JS
Which compressor/s to use when compressing JavaScript files. Currently
"yuicompressor", "closure-compiler" and "uglify-js" (>= 2.0) are
supported. For more information see the documentation for compress_js() in the
asset module. Defaults to "uglify-js".

DETA_COMPRESSOR_CSS
Which compressor/s to use when compressing CSS files. Currently "yuicompressor"
"clean-css" and "sqwish" are supported. For more information see the documentation
for compress_css() in the asset module. Defaults to "yuicompressor".

COMPRESSOR_PNG
Compressor/s to use when compressing PNG files. Currently
"pngcrush" and "pngquant" are supported.

COMPRESSOR_JPG
Compressor/s to use when compressing JPG files. Currently
"imagemagick" and "jpegtran" is supported.

-- Multiple compressors are delimited by a space. --

DETA_CACHE_DIR
Directory which holds the cached items for the internal cache. Will be created
if it doesn't exist. Caches asset compressions. Defaults to "/tmp/deta_cache".

Terminology
-----------
Tasks
'''''
Tasks are sourced by the deta tool they automatically have access to all
the env configurations (loaded from *.conf).

Following global variables are always available within tasks:
QUIET (y|n), DRYRUN (y|n), DETA (deta directory), TASK (current task),
CONTEXT (current environment context).

Task are plain text files using `KEY=VALUE` for defining configuration
variables and `#` for comments.

Tasks can be located wherever you want. In the end you just pass the path to
the deta tool. However it is nice to be able to group tasks, therefore it is
suggested to create subdirectories directly in the `bin` directory.

Modules
'''''''
Modules contain sets of functions and are loaded on demand by sourcing
them in the beginning of each task. Modules shipped with deta are located
in the directory specified by $DETA. Of course you can also built your own
modules and load them in a similar way.

```
source $DETA/g11n.sh
source $DETA/sys.sh
# ...
```

By default the core module is always loaded, making functions as role and
defer available in any task.

Environment Configuration
'''''''''''''''''''''''''
Environments (or env for short) allow you to keep host specific configuration
settings in one place. This configuration is kept is an file in the root
of the project (named "Envfile").

To use the environment configuration simply add `role THIS` to the
top of your task. After this the configuration is available in
variables prefixed with "THIS_".