From 5acf0e4a3cfafca569a9e22f1730f11c8c6a4a07 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sat, 21 Sep 2013 13:51:27 -0500 Subject: add overview, overlays and configuration pages --- configuration/index.md | 213 +++++++++++++++++++++++++++++++++++++++++++++++++ overlays/index.md | 56 +++++++++++++ overview/index.md | 64 +++++++++++++++ 3 files changed, 333 insertions(+) create mode 100644 configuration/index.md create mode 100644 overlays/index.md create mode 100644 overview/index.md 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, [, , ...]}. +``` + +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, []}. + +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}, + } + {release, {relname, vsn}, + {erts, vsn}, + } + +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, }. + +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, }. + +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 + %% {, }. + {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 `(:)` +* *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.* : The override directory for said +* *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 `` +* *release.[AppName].dir : The on system directory of `` +* *release.[AppName].active_dependencies : The list of active application dependencies for `` +* *release.[AppName].library_dependencies : The list of library application dependencies for `` +* *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. -- cgit v1.2.3