add overview, overlays and configuration pages

3 files changed, 333 insertions, 0 deletions

diff --git a/configuration/index.md b/configuration/index.md
new file mode 100644
index 0000000..b73f393
--- /dev/null
+++ b/configuration/index.md
@@ -0,0 +1,213 @@
+---
+layout: default
+title: Relx Configuration
+---
+
+Configuration
+=============
+
+Configuration of reltool is done via Erlang key-value elements in the
+`relx.config` file(s). There are various configuration elements
+that can appear, each affects the running of the release building
+process in specific ways. Note that these must be complete Erlang
+terms terminated by a `.`.
+
+App Dirs
+--------
+
+App directories specify where `relx` will search for OTP applications to resolve dependencies.
+
+The app directory configuration element looks as follows:
+
+```
+{lib_dirs, [<path1>, <path2>, ...]}.
+```
+
+Paths
+-----
+
+Paths is a way to add additional code paths (that point to Erlang beam
+files) to the system. These are not used for dependency resolution,
+they are only used as code paths. The main use for this is simply to
+provide a non-resolvable path for additional providers.
+
+The path configuration element looks as follows:
+
+    {paths, [<list of directory paths>]}.
+
+So if we wanted to add `/usr/local/lib` and `/opt/lib` to the code
+paths for the system we could add the following::
+
+    {paths, ["/usr/local/lib", "/opt/lib"]}.
+
+to our configuration.
+
+Releases
+--------
+
+Release configuration is the bread and butter, the blood and bones of
+the Relx system. It provides the framework for realizing
+dependencies in the system. The release element basically minics the
+standard _Erlang/OTP Release Metadata file format:
+http://www.erlang.org/doc/man/rel.html. There are two main
+differences. The first is that you don't have to specify a complete
+list of applications and you may specify version constraints instead
+of hard versions.
+
+
+    {release, {relname, vsn},
+      <app goals>}
+    {release, {relname, vsn},
+     {erts, vsn},
+      <app goals>}
+
+See the [[Overview]] for goal syntax.
+
+Start Script
+------------
+
+Relx generates a start script by default that should work for your
+release. However, there may be times when you want to provide a custom
+start script. In those situations you may disable automatic start
+script creation by adding the following to your `relx.config`.
+
+    {generate_start_script, false}.
+
+
+Overlays
+--------
+
+These are documented on the [[Overlays]] wiki page. Go there for more
+information.
+
+Advanced Options
+----------------
+
+The following are options that you would probably not need to use very
+often. They exist for doing unusual things with the system or adding
+plugin style functionality.
+
+
+### Providers
+
+Providers are how the Relx system can be extended by a user. They
+are basically Erlang modules that implement the `rcl_provider`
+behaviour and are available via a code path. See the section on
+providers for more information.
+
+The `providers` element provides a completely new list of providers,
+replacing any providers that may already exist. The provider element
+is as follows::
+
+     {providers, <list of module names>}.
+
+Lets say I have three providers; `my_custom_assembler`,
+`my_rpm_assembler` and `my_deb_assembler`. I could make these the
+complete list of providers by doing the following in my config::
+
+    {providers, [my_custom_assembler,
+                 my_rpm_assembler,
+                 my_deb_assembler]}.
+
+Order is important in the providers as they will be executed in the
+order specified.
+
+### Add Providers
+
+`add_providers` is very similar to `providers` with the exception that
+the listed providers are added to the end of the current list of
+providers rather then replacing the list all together. Add providres
+looks as follows::
+
+
+     {add_providers, <list of module names>}.
+
+Lets take our previous example but only add `my_rpm_assembler` and
+`my_deb_assembler` to the existing list of providers. We do this by
+adding the following::
+
+    {add_providers, [my_rpm_assembler,
+                     my_deb_assembler]}.
+
+Example Configuration
+---------------------
+
+```Erlang
+%% -*- mode: Erlang; fill-column: 80; comment-column: 75; -*-
+%% Example Relx Config
+%% ======================
+%%
+%% This is an example relx config whose purpose is to demonstrate all of the
+%% options available in relx. Its not expected that you will use all of the
+%% things here. In fact, there is a high likely hood that *your* relx.config
+%% will be extremely minimal, as relx does a very good job of figuring out
+%% things on its own.
+%%
+%% The Release We Are Building
+%% ---------------------------
+%%
+%% Lets say we have a release called sexpr. The sexpr release supports versions
+%% 0.0.1 and 0.0.2 with different dependencies. 0.0.1 requires erlware commons
+%% 0.8.0 or lesser. 0.0.2 requires erlware_commons 0.8.1 or greater along with
+%% neotoma (any version). We also do not want neotoma to be loaded. We also want
+%% our default release. the one we build in the common case to be sexper 0.0.2.
+
+%% You can tell relx about additional directories that you want searched for
+%% otp apps during the discovery process. You do that in the 'lib_dirs' config.
+%% You can specify these on the command line with `-l`.
+{lib_dirs, ["../erlang_app"]}.
+
+%% You can also specify these paths on the command line with `-p`. Be aware that
+%% relx plays well with rebar so if you have a deps directory in the current
+%% directory it will be automatically added.
+{paths, ["/opt/erlang_apps"]}.
+
+
+%% If you have a sys.config file you need to tell relx where it is. If you do
+%% that relx will include the sys.config in the appropriate place
+%% automatically.
+{sys_config, "./config/sys.config"}.
+
+%% relx will include erts by default. However, if you don't want to include
+%% erts you can add the `include_erts` tuple to the config and tell relx not
+%% to include it.
+{include_erts, false}.
+
+%% When we have multiple releases relx needs to know which one to build. You
+%% can specify that on the command line with the `-n` and `-v` arguments to
+%% relx. However, it is often more convenient to do it in the config.
+{default_release, sexpr, "0.0.2"}.
+
+{release, {sexpr, "0.0.1"},
+ [sexpr,
+  %% There are two syntaxes for constraints.
+  %% The first is the tuple syntax shown here.
+  {erlware_commons, "0.8.0", '<='}]}.
+
+{release, {sexpr, "0.0.2"},
+ [sexpr,
+
+  %% This is the second constraint syntax, it is interchangeable with the tuple
+  %% syntax and its up to you which you find more readable/usable.
+  "erlware_commons>=0.8.1",
+
+  %% You can put the release load types in the release spec here in exactly the
+  %% same way that you can do it for a normal relfile. The syntax is
+  %% {<constraint>, <type>}.
+  {neotoma, load}]}.
+
+%% During development its often the case that you want to substitute the app
+%% that you are working on for a 'production' version of an app. You can
+%% explicitly tell relx to override all versions of an app that you specify
+%% with an app in an arbitrary directory. Relx will then symlink that app
+%% into the release in place of the specified app. be aware though that relx
+%% will check your app for consistancy so it should be a normal OTP app and
+%% already be built.
+{overrides, [{sexpr, "../sexpr"}]}.
+
+
+%% In some cases you might want to add additional functionality to relx. You
+%% can do this via a 'provider'. A provider is an implementation of the relx
+%% provider behaviour. This probably shouldn't be needed very often.
+{add_providers, [my_custom_functionality]}.
+```
diff --git a/overlays/index.md b/overlays/index.md
new file mode 100644
index 0000000..a6b6c4e
--- /dev/null
+++ b/overlays/index.md
@@ -0,0 +1,56 @@
+---
+layout: default
+title: Relx Overlays
+---
+
+Overlays
+========
+
+Overlays as defined in Rebar are directly supported in Relx. So you
+can take your Overlay configuration and move it to your
+`relx.config` and it should just work. For example, you could take
+the following:
+
+    {overlay_vars, "vars.config"}.
+    {overlay, [{mkdir, "log/sasl"},
+                {copy, "files/erl", "{{erts_vsn}}/bin/erl"},
+                {copy, "files/nodetool", "{{erts_vsn}}/bin/nodetool"},
+                {template, "files/app.config", "etc/app.config"},
+                {template, "files/vm.args", "etc/vm.args"}]}.
+
+and move it directly from your `reltool.config` to your
+`relx.config` and it would work in exactly the same way. In Relx
+you have more options though. Relx exposes more variables along
+with the full power of a Django templating system (see
+[erlydtl](http://code.google.com/p/erlydtl/)). You can look at the
+documentation there for the full syntax supported. The variables
+supported are listed below.
+
+Available Variables
+-------------------
+
+* *log* : The current log level in the format of `(<logname>:<loglevel>)`
+* *output_dir* : The current output directory for the built release
+* *target_dir* : The same as `output_dir`, exists for backwards compatibility
+* *overridden* : The current list of overridden apps (a list of app names)
+* *overrides.<AppName>* : The override directory for said <AppName>
+* *goals* : The list of user specified goals in the system
+* *lib_dirs* : The list of library directories, both user specified and derived
+* *config_file* : The list of config file used in the system
+* *providers* : The list of provider names used for this run of relx
+* *sys_config* : The location of the sys config file
+* *root_dir* : The root dir of the current project
+* *default_release_name* : The current default release name for the relx run
+* *default_release_version* : The current default release version for the relx run
+* *default_release* : The current default release for the relx run
+* *release_erts_version* :  The version of the Erlang Runtime System in use
+* *erts_vsn* : The same as `release_erts_vsn` (for backwards compatibility)
+* *release_name* : The currently executing release
+* *release_version* : the currently executing version
+* *rel_vsn* : Same as `release_version`. Exists for backwards compatibility
+* *release_applications* : A list of applications included in the release
+* *release.[AppName].version : The version of `<AppName>`
+* *release.[AppName].dir : The on system directory of `<AppName>`
+* *release.[AppName].active_dependencies : The list of active application dependencies for `<AppName>`
+* *release.[AppName].library_dependencies : The list of library application dependencies for `<AppName>`
+* *release.[AppName].link : Indicates if this application should be linked in or not
diff --git a/overview/index.md b/overview/index.md
new file mode 100644
index 0000000..66e1a5f
--- /dev/null
+++ b/overview/index.md
@@ -0,0 +1,64 @@
+---
+layout: default
+title: Relx Overview
+---
+
+Overview
+========
+
+Relx is a tool that, given a specification, assembles
+releases. That is it makes an assessment of all of the Erlang/OTP Apps
+available to it and the constraints that you supply as part of your
+configuration and resolves a complete set of OTP Applications and
+thier versions for use in the release. This may be a bit hard to
+understand if you are not familiar with the way version resolutions
+work in package management systems. So lets look at an example.
+
+Lets say that you have the following OTP Applications
+
+     app1-1.2
+      with dependencies
+        app2
+        app5
+        app6
+    app1-1.3
+     with dependencies
+       app2
+       app6
+    app2-2.0
+     with dependencies
+       app6
+    app2-2.1
+     with dependencies
+       app6
+       app7
+    app3-2.0
+    app4-1.0.0
+    app5-3.0
+    app6-1.0
+     with dependencies
+       app3
+    app7-2.0
+
+This is the world of OTP Apps your Relx knows about (basically OTP
+Apps in the Library Directories you have specified). You have set a
+config that looks like the following:
+
+     {release, {awesome_supercool, "1.0"},
+        [{app1, "1.3", '>='},
+         {app2, "2.0", '>'},
+         app3]}
+
+When the Relx process has run you will end up with a complete
+release as follows
+
+    {release, {awesome_supercool, "1.0"},
+      [{app1, "1.3"},
+       {app2, "2.1"},
+       {app3, "2.0"},
+       {app6, "1.0"},
+       {app7, "2.0"}]}
+
+As you can see that is a fully realied view of your direct and
+transative dependencies based on the world that Relx knows about
+and the constraints that you specified in your configuration.