diff options
Diffstat (limited to 'configuration/index.md')
| -rw-r--r-- | configuration/index.md | 213 |
1 files changed, 213 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]}. +``` |