diff options
| -rw-r--r-- | CONTRIBUTING.md | 371 | ||||
| -rw-r--r-- | README.md | 277 |
2 files changed, 409 insertions, 239 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ce1e93..f175cc2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,129 +1,322 @@ -Contributing to rebar ---------------------- +# Contributing to Rebar3 -Before implementing a new feature, please submit a ticket to discuss your plans. -The feature might have been rejected already, or the implementation might already be decided. +1. [License](#license) +2. [Submitting a bug](#submitting-a-bug) +3. [Requesting or implementing a feature](#requesting-or-implementing-a-feature) +4. [Project Structure](#project-structure) +5. [Tests](#tests) +6. [Submitting your changes](#submitting-your-changes) + 1. [Code Style](#code-style) + 2. [Committing your changes](#committing-your-changes) + 3. [Pull Requests and Branching](#pull-requests-and-branching) + 4. [Credit](#credit) -See [Community and Resources](README.md#community-and-resources). +## License ## -Code style ----------- +Rebar3 is licensed under the [Apache License 2.0](LICENSE) for all new code. +However, since it is built from older code bases, some files still hold other +free licenses (such as BSD). Where it is the case, the license is added in +comments. + +All files without specific headers can safely be assumed to be under Apache +2.0. + +## Submitting a Bug + +Bugs can be submitted to the [Github issue page](https://github.com/rebar/rebar3/issues). + +Rebar3 is not perfect software and will be buggy. When submitting a bug, be +careful to know the following: + +- The Erlang version you are running +- The Rebar3 version you are using +- The command you were attempting to run + +This information can be automatically generated to put into your bug report +by calling `rebar3 report "my command"`. + +You may be asked for further information regarding: + +- Your environment, including the Erlang version used to compile rebar3, + details about your operating system, where your copy of Erlang was installed + from, and so on; +- Your project, including its structure, and possibly to remove build + artifacts to start from a fresh build +- What it is you are trying to do exactly; we may provide alternative + means to do so. + +If you can provide an example code base to reproduce the issue on, we will +generally be able to provide more help, and faster. + +All contributors and rebar3 maintainers are generally unpaid developers +working on the project in their own free time with limited resources. We +ask for respect and understanding and will try to provide the same back. + +## Requesting or implementing a feature + +Before requesting or implementing a new feature, please do the following: + +- Take a look at our [list of plugins](http://www.rebar3.org/docs/using-available-plugins) + to know if the feature isn't already supported by the community. +- Verify in existing [tickets](https://github.com/rebar/rebar3/issues) whether + the feature might already is in the works, has been moved to a plugin, or + has already been rejected. + +If this is done, open up a ticket. Tell us what is the feature you want, +why you need it, and why you think it should be in rebar3 itself. + +We may discuss details with you regarding the implementation, its inclusion +within the project or as a plugin. Depending on the feature, we may provide +full support for it, or ask you to help implement and/or commit to maintaining +it in the future. We're dedicated to providing a stable build tool, and may +also ask features to exist as a plugin before being included in core rebar3 -- +the migration path from one to the other is fairly simple and little to no code +needs rewriting. + +## Project Structure + +Rebar3 is an escript built around the concept of providers. Providers are the +modules that do the work to fulfill a user's command. They are documented in +[the official documentation website](http://www.rebar3.org/docs/plugins#section-provider-interface). + +Example provider: + +```erlang +-module(rebar_prv_something). + +-behaviour(rebar_provider). + +-export([init/1, + do/1, + format_error/1]). + +-define(PROVIDER, something). +-define(DEPS, []). + +%% =================================================================== +%% Public API +%% =================================================================== + +-spec init(rebar_state:state()) -> {ok, rebar_state:state()}. +init(State) -> + State1 = rebar_state:add_provider(State, rebar_provider:create([ + {name, ?PROVIDER}, + {module, ?MODULE}, + {bare, true}, + {deps, ?DEPS}, + {example, "rebar dummy"}, + {short_desc, "dummy plugin."}, + {desc, ""}, + {opts, []} + ])), + {ok, State1}. -The following rules apply: - * Do not introduce trailing whitespace - * We use spaces for indenting only - * Try not to introduce lines longer than 80 characters - * Write small functions whenever possible - * Avoid having too many clauses containing clauses containing clauses. - Basically, avoid deeply nested functions. +-spec do(rebar_state:state()) -> {ok, rebar_state:state()}. +do(State) -> + %% Do something + {ok, State}. -Follow the indentation style of existing files. The [erlang-mode for -(emacs)](http://www.erlang.org/doc/man/erlang.el.html) indentation is going to -always work. Other users may want to use 4-width spaces and make sure things -align mostly the way they would with Emacs code, or with the rest of the -project. +-spec format_error(any()) -> iolist(). +format_error(Reason) -> + io_lib:format("~p", [Reason]). +``` -Where possible, include type specifications for your code so type analysis -will be as accurate as possible. +Providers are then listed in `rebar.app.src`, and can be called from +the command line or as a programmatical API. -Please add comments around tricky fixes or workarounds so that we can -easily know why they're there at a glance. +All commands are therefore implemented in standalone modules. If you call +`rebar3 <task>`, the module in charge of it is likely located in +`src/rebar_prv_<task>.erl`. -Pull requests and branching ---------------------------- +Templates are included in `priv/templates/` -All fixes to rebar end up requiring a +1 from one or more of the project's -maintainers. When opening a pull request, explain what the patch is doing -and if it makes sense, why the proposed implementation was chosen. +The official test suite is Common Test, and tests are located in `test/`. -Try to use well-defined commits (one feature per commit) so that reading -them and testing them is easier for reviewers and while bissecting the code -base for issues. +Useful modules include: +- `rebar_api`, providing an interface for plugins to call into core rebar3 + functionality +- `rebar_core`, for initial boot and setup of a project +- `rebar_config`, handling the configuration of each project. +- `rebar_app_info`, giving access to the metadata of a specific OTP application + in a project. +- `rebar_base_compiler`, giving a uniform interface to compile `.erl` files. +- `rebar_dir` for directory handling and management +- `rebar_file_util` for cross-platform file handling +- `rebar_state`, the glue holding together a specific build or task run; + includes canonical versions of the configuration, profiles, applications, + dependencies, and so on. +- `rebar_utils` for generic tasks and functionality required across + multiple providers or modules. -During the review process, you may be asked to correct or edit a few things -before a final rebase to merge things. - -Please work in feature branches, and do not commit to `master` in your fork. - -Provide a clean branch without merge commits. +## Tests -Tests ------ +Rebar3 tries to have as many of its features tested as possible. Everything +that a user can do and should be repeatable in any way should be tested. -As a general rule, any behavioral change to rebar requires a test to go with -it. If there's already a test case, you may have to modify that one. If there -isn't a test case or a test suite, add a new test case or suite in `test/`. +Tests are written using the Common Test framework. Tests for rebar3 can be run +by calling: -To run the tests: - -```sh -$ ./bootstrap +```bash +$ rebar3 escriptize # or bootstrap $ ./rebar3 ct ``` -The rebar3 test suite is written using Common Test. As many of the tests as -possible are written by using the programmatic rebar3 API rather than -by running the escriptized project directly. The tests should be restricted -to their `priv_dir` and leave the system clean after a run. +Most tests are named according to their module name followed by the `_SUITE` +suffi. Providers are made shorter, such that `rebar_prv_new` is tested in +`rebar_new_SUITE`. + +Most tests in the test suite will rely on calling Rebar3 in its API form, +then investigating the build output. Because most tests have similar +requirements, the `test/rebar_test_utils` file contains common code +to set up test projects, run tasks, and verify artifacts at once. + +A basic example can look like: + +```erlang +-module(rebar_some_SUITE). +-compile(export_all). +-include_lib("common_test/include/ct.hrl"). +-include_lib("eunit/include/eunit.hrl"). + +all() -> [checks_success, checks_failure]. + +init_per_testcase(Case, Config0) -> + %% Create a project directory in the test run's priv_dir + Config = rebar_test_utils:init_rebar_state(Config0), + %% Create toy applications + AppDir = ?config(apps, Config), + Name = rebar_test_utils:create_random_name("app1_"++atom_to_list(Case)), + Vsn = rebar_test_utils:create_random_vsn(), + rebar_test_utils:create_app(AppDir, Name, Vsn, [kernel, stdlib]), + %% Add the data to the test config + [{name, Name} | Config]. + +end_per_testcase(_, Config) -> + Config. + +checks_success(Config) -> + %% Validates that the application in `name' is successfully compiled + Name = ?config(name, Config), + rebar_test_utils:run_and_check(Config, [], + ["compile"], + {ok, [{app, Name}]}). + +checks_failure(Config) -> + %% Checks that a result fails + Command = ["fakecommand", "fake-arg"], + rebar_test_utils:run_and_check( + Config, [], Command, + {error, io_lib:format("Command ~p not found", [fakecommand])} + ). +``` - If such tests prove hard to write, you can ask for help doing that in your -pull request. +The general interface to `rebar_test_utils:run_and_check` is +`run_and_check(CTConfig, RebarConfig, Command, Expect)` where `Expect` can +be any of: + +```erlang +{ok, OKRes} +{ok, OKRes, ProfilesUsed} +{error, Reason} + +% where: +ProfilesUsed :: string() % matching the profiles to validate (defaults to "*") +OKRes :: {app, Name} % name of an app that is in the build directory + | {app, Name, valid} % name of an app that is in the build directory and compiled properly + | {app, Name, invalid} % name of an app that didn't compile properly + | {dep, Name} % name of a dependency in the build directory + | {dep, Name, Vsn} % name of a dependency in the build directory with a specific version + | {dep_not_exist, Name} % name of a dependency missing from the build directory + | {checkout, Name} % name of an app that is a checkout dependency + | {plugin, Name} % name of a plugin in the build directory + | {plugin, Name, Vsn} % name of a plugin in the build directory with a specific version + | {global_plugin, Name} % name of a global plugin in the build directory + | {global_plugin, Name, Vsn} % name of a global plugin in the build directory with a specific version + | {lock, Name} % name of a locked dependency + | {lock, Name, Vsn} % name of a locked dependency of a specific version + | {lock, pkg, Name, Vsn}% name of a locked package of a specific version + | {lock, src, Name, Vsn}% name of a locked source dependency of a specific version + | {release, Name, Vsn, ExpectedDevMode} % validates a release + | {tar, Name, Vsn} % validates a tarball's existence + | {file, Filename} % validates the presence of a given file + | {dir, Dirname} % validates the presence of a given directory +Reason :: term() % the exception thrown by rebar3 +``` -For tests having a lot to do with I/O and terminal interaction, consider -adding them to https://github.com/tsloughter/rebar3_tests +This generally lets most features be tested fine. Ask for help if you cannot +figure out how to write tests for your feature or patch. +## Submitting your changes -Credit ------- +While we're not too formal when it comes to pull requests to the project, +we do appreciate users taking the time to conform to the guidelines that +follow. -To give everyone proper credit in addition to the git history, please feel free to append -your name to `THANKS` in your first contribution. +We do expect all pull requests submitted to come with [tests](#tests) before +they are merged. If you cannot figure out how to write your tests properly, ask +in the pull request for guidance. + +### Code Style -Committing your changes ------------------------ + * Do not introduce trailing whitespace + * Indentation is 4 spaces wide, no tabs. + * Try not to introduce lines longer than 80 characters + * Write small functions whenever possible, and use descriptive names for + functions and variables. + * Avoid having too many clauses containing clauses containing clauses. + Basically, avoid deeply nested `case ... of` or `try ... catch` expressions. + Break them out into functions if possible. + * Comment tricky or non-obvious decisions made to explain their rationale. -Please ensure that all commits pass all tests, and do not have extra Dialyzer warnings. -To do that run `./rebar3 ct` and `./rebar3 as dialyze dialyzer`. +### Committing your changes -#### Structuring your commits +It helps if your commits are structured as follows: - Fixing a bug is one commit. - Adding a feature is one commit. - Adding two features is two commits. - Two unrelated changes is two commits (and likely two Pull requests) -If you fix a (buggy) commit, squash (`git rebase -i`) the changes as a fixup commit into -the original commit. +If you fix a (buggy) commit, squash (`git rebase -i`) the changes as a fixup +commit into the original commit, unless the patch was following a +maintainer's code review. In such cases, it helps to have separate commits. -#### Writing Commit Messages +The reviewer may ask you to later squash the commits together to provide +a clean commit history before merging in the feature. -It's important to write a proper commit title and description. The commit title must be -at most 50 characters; it is the first line of the commit text. The second line of the -commit text must be left blank. The third line and beyond is the commit message. You -should write a commit message. If you do, wrap all lines at 72 characters. You should -explain what the commit does, what references you used, and any other information -that helps understanding your changes. +It's important to write a proper commit title and description. The commit title +should fir around 50 characters; it is the first line of the commit text. The +second line of the commit text must be left blank. The third line and beyond is +the commit message. You should write a commit message. If you do, wrap all +lines at 72 characters. You should explain what the commit does, what +references you used, and any other information that helps understanding your +changes. -Basically, structure your commit message like this: +### Pull Requests and Branching -<pre> -One line summary (at most 50 characters) +All fixes to rebar end up requiring a +1 from one or more of the project's +maintainers. When opening a pull request, explain what the patch is doing +and if it makes sense, why the proposed implementation was chosen. -Longer description (wrap at 72 characters) -</pre> +Try to use well-defined commits (one feature per commit) so that reading +them and testing them is easier for reviewers and while bissecting the code +base for issues. -##### Commit title/summary +During the review process, you may be asked to correct or edit a few things +before a final rebase to merge things. Do send edits as individual commits +to allow for gradual and partial reviews to be done by reviewers. Once the +1s +are given, rebasing is appreciated but not mandatory. -* At most 50 characters -* What was changed -* Imperative present tense (Fix, Add, Change) - * `Fix bug 123` - * `Add 'foobar' command` - * `Change default timeout to 123` -* No period +Please work in feature branches, and do not commit to `master` in your fork. + +Provide a clean branch without merge commits. -##### Commit description +If you can, pick a descriptive title for your pull request. When we generate +changelogs before cutting a release, a script uses the pull request names +to populate the entries. -* Wrap at 72 characters -* Why, explain intention and implementation approach -* Present tense + +### Credit + +To give everyone proper credit in addition to the git history, please feel free to append +your name to `THANKS` in your first contribution. @@ -1,163 +1,138 @@ -rebar -===== - -rebar [3.0](#30) is an Erlang build tool that makes it easy to compile and test Erlang -applications, port drivers and releases. +# Rebar3 [](https://travis-ci.org/rebar/rebar3) [](https://ci.appveyor.com/project/TristanSloughter/rebar3) -rebar is a self-contained Erlang script, so it's easy to distribute or even -embed directly in a project. Where possible, rebar uses standard Erlang/OTP -conventions for project structures, thus minimizing the amount of build -configuration work. rebar also provides dependency management, enabling -application writers to easily re-use common libraries from a variety of -locations ([hex.pm](http://hex.pm), git, hg, and so on). - -3.0 Beta-4 -==== - -[DOCUMENTATION](http://www.rebar3.org/v3.0/docs) - -### Commands - -| Command | Description | -|----------- |------------ | -| as | Higher-order provider to run multiple tasks in sequence as certain profiles | -| compile | Build project | -| clean | Remove project apps beam files | -| cover | Generate coverage info from data compiled by `eunit --cover` or `ct --cover` | -| ct | Run Common Test suites | -| deps | Lists dependencies currently in use | -| do | Higher-order provider to run multiple tasks in sequence | -| dialyzer | Run the Dialyzer analyzer on the project | -| edoc | Generate documentation using edoc | -| escriptize | Generate escript of project | -| eunit | Run eunit tests | -| help | Print help for rebar or task | -| new | Create new rebar project from templates | -| path | Print paths to build dirs in current profile | -| pkgs | List available packages | -| plugins | List or upgrade plugins | -| release | Build release of project | -| relup | Creates relup from 2 releases | -| report | Report on environment and versions for bug reports | -| shell | Run shell with project apps in path | -| tar | Package release into tarball | -| tree | Print dependency tree | -| unlock | Unlock dependencies | -| unstable | Namespace providing commands that are still in flux | -| update | Update package index | -| upgrade | Fetch latest version of dep | -| version | Print current version of Erlang/OTP and rebar | -| xref | Run cross reference analysis on the project | - -A more complete list can be found on the [docs page](http://www.rebar3.org/v3.0/docs/commands) - -### Changes - -#### Since Rebar 2.x - -* Fetches and builds deps if missing when running any command that relies on them -* Automatically recognizes `apps` and `lib` directory structure -* Relx for releases and relups -* deterministic builds and conflict resolution -* New plugin handling mechanism -* New hook mechanism -* Support for packages -* A ton more - -### Gone - -* Reltool integeration -* Quickcheck integration (moved to [a plugin](http://www.rebar3.org/v3.0/docs/using-available-plugins#quickcheck)) -* C code compiling (moved to [a plugin](http://www.rebar3.org/v3.0/docs/using-available-plugins#port-compiler) or hooks) - -### Providers - -Providers are the modules that do the work to fulfill a user's command. - -Example: - -```erlang --module(rebar_prv_something). - --behaviour(rebar_provider). - --export([init/1, - do/1, - format_error/1]). - --define(PROVIDER, something). --define(DEPS, []). - -%% =================================================================== -%% Public API -%% =================================================================== - --spec init(rebar_state:state()) -> {ok, rebar_state:state()}. -init(State) -> - State1 = rebar_state:add_provider(State, rebar_provider:create([{name, ?PROVIDER}, - {module, ?MODULE}, - {bare, false}, - {deps, ?DEPS}, - {example, "rebar dummy"}, - {short_desc, "dummy plugin."}, - {desc, ""}, - {opts, []}])), - {ok, State1}. - --spec do(rebar_state:state()) -> {ok, rebar_state:state()}. -do(State) -> - %% Do something - {ok, State}. - --spec format_error(any()) -> iolist(). -format_error(Reason) -> - io_lib:format("~p", [Reason]). +1. [What is Rebar3?](#what-is-rebar3) +2. [Why Rebar3?](#why-rebar3) +3. [Should I Use Rebar3?](#should-i-use-rebar3) +4. [Getting Started](#getting-started) +5. [Documentation](#documentation) +6. [Features](#features) +7. [Migrating from rebar2](#migrating-from-rebar2) +8. [Additional Resources](#additional-resources) + +## What is Rebar3 + +Rebar3 is an Erlang tool that makes it easy to create, develop, and +release Erlang libraries, applications, and systems in a repeatable manner. + +Rebar3 will: +- respect and enforce standard Erlang/OTP conventions for project + structure so they are easily reusable by the community; +- manage source dependencies and Erlang [packages](http://hex.pm) + while ensuring repeatable builds; +- handle build artifacts, paths, and libraries such that standard + development tools can be used without a headache; +- adapt to projects of all sizes on almost any platform; +- treat [documentation](http://www.rebar3.org/docs/) as a feature, + and errors or lack of documentation as a bug. + +Rebar3 is also a self-contained Erlang script. It is easy to distribute or +embed directly in a project. Tasks or behaviours can be modified or expanded +with a [plugin system](http://www.rebar3.org/docs/using-available-plugins) +[flexible enough](http://www.rebar3.org/docs/plugins) that even other languages +on the Erlang VM will use it as a build tool. + +## Why Rebar3 + +Rebar3 is the spiritual successor to [rebar +2.x](https://github.com/rebar/rebar), which was the first usable build tool +for Erlang that ended up seeing widespread community adoption. It however +had several shortcomings that made it difficult to use with larger projects +or with teams with users new to Erlang. + +Rebar3 was our attempt at improving over the legacy of Rebar 2.x, providing the +features we felt it was missing, and to provide a better environment in which +newcomers joining our teams could develop. + +## Should I use Rebar3? + +If your main language for your system is Erlang, that you value repeatable builds +and want your various tools to integrate together, we do believe Rebar3 is the +best experience you can get. + +## Getting Started + +A [getting started guide is maintained on the offcial documentation website](http://www.rebar3.org/docs/getting-started), +but installing rebar3 can be done by any of the ways described below + +Nightly compiled version: +```bash +$ wget https://s3.amazonaws.com/rebar3/rebar3 && chmod +x rebar3 ``` +From Source (assuming you have a full Erlang install): -Building --------- - -Recommended installation of [Erlang/OTP](http://www.erlang.org) is source built using [erln8](http://erln8.github.io/erln8/) or [kerl](https://github.com/yrashk/kerl). For binary packages use those provided by [Erlang Solutions](https://www.erlang-solutions.com/downloads/download-erlang-otp), but be sure to choose the "Standard" download option or you'll have issues building projects. - -### Dependencies - -To build rebar you will need a working installation of Erlang R15 (or later). - -Should you want to clone the rebar repository, you will also require git. - -#### Downloading - -You can download a pre-built binary version of rebar3 based on the last commit from: - -https://s3.amazonaws.com/rebar3/rebar3 - -#### Bootstrapping rebar3 - -```sh -$ git clone https://github.com/rebar/rebar3 +```bash +$ git clone https://github.com/rebar/rebar3.git $ cd rebar3 $ ./bootstrap ``` -### Developing on rebar3 - -When developing you can simply run `escriptize` to build your changes but the new escript is under `_build/default/bin/rebar3` - -```sh -$ ./rebar3 escriptize -$ _build/default/bin/rebar3 -``` - -Contributing to rebar -===================== - -Please refer to [CONTRIBUTING](CONTRIBUTING.md). - -Community and Resources ------------------------ +Stable versions can be obtained from the [releases page](https://github.com/rebar/rebar3/releases). + +Rebar3 may also be available on various OS-specific package managers such as +FreeBSD Ports. Those are maintained by the community and Rebar3 maintainers +themselves are generally not involved in that process. + +If you do not have a full Erlang install, we using [erln8](http://erln8.github.io/erln8/) +or [kerl](https://github.com/yrashk/kerl). For binary packages use those provided +by [Erlang Solutions](https://www.erlang-solutions.com/downloads/download-erlang-otp), +but be sure to choose the "Standard" download option or you'll have issues building +projects. + +## Documentation + +Rebar3 documentation is maintained on [http://www.rebar3.org/docs](http://www.rebar3.org/docs) + +## Features + +Rebar3 supports the following features or tools by default, and may provide many +others via the plugin ecosystem: + +| features | Description | +|--------------------- |------------ | +| Command composition | Rebar3 allows multiple commands to be run in sequence by calling `rebar3 do <task1>,<task2>,...,<taskN>`. | +| Command dependencies | Rebar3 commands know their own dependencies. If a test run needs to fetch dependencies and build them, it will do so. | +| Command namespaces | Allows multiple tools or commands to share the same name. | +| Compiling | Build the project, including fetching all of its dependencies by calling `rebar3 compile` | +| Clean up artifacts | Remove the compiled beam files from a project with `rebar3 clean` or just remove the `_build` directory to remove *all* compilation artifacts | +| Code Coverage | Various commands can be instrumented to accumulate code coverage data (such as `eunit` or `ct`). Reports can be generated with `rebar3 cover` | +| Common Test | The test framework can be run by calling `rebar3 ct` | +| Dependencies | Rebar3 maintains local copies of dependencies on a per-project basis. They are fetched deterministically, can be locked, upgraded, fetched from source, packages, or from local directories. See [Dependencies on the documentation website](http://www.rebar3.org/docs/dependencies). Call `rebar3 tree` to show the whole dependency tree. | +| Documentation | Print help for rebar3 itself (`rebar3 help`) or for a specific task (`rebar3 help <task>`). Full reference at [www.rebar3.org](http://www.rebar3.org/docs). | +| Dialyzer | Run the Dialyzer analyzer on the project with `rebar3 dialyzer`. Base PLTs for each version of the language will be cached and reused for faster analysis | +| Edoc | Generate documentation using edoc with `rebar3 edoc` | +| Escript generation | Rebar3 can be used to generate [escripts](http://www.erlang.org/doc/man/escript.html) providing an easy way to run all your applications on a system where Erlang is installed | +| Eunit | The test framework can be run by calling `rebar3 eunit` | +| Locked dependencies | Dependencies are going to be automatically locked to ensure repeatable builds. Versions can be changed with `rebar3 upgrade` or `rebar3 upgrade <app>`, or locks can be released altogether with `rebar3 unlock`. | +| Packages | [Hex packages](http://hex.pm) can be listed with `rebar3 pkgs`. They can be used as dependencies, will be cached locally for faster usage, and a local index will be used and updated with `rebar3 update`. | +| Path | While paths are managed automatically, you can print paths to the current build directories with `rebar3 path`. | +| Plugins | Rebar3 can be fully extended with [plugins](#http://www.rebar3.org/docs/using-available-plugins). List or upgrade plugins by using the plugin namespace (`rebar3 plugins`). | +| Profiles | Rebar3 can have subconfiguration options for different profiles, such as `test` or `prod`. These allow specific dependencies or compile options to be used in specific contexts. See [Profiles](http://www.rebar3.org/docs/profiles) in the docs. | +| Releases | Rebar3 supports [building releases](http://www.rebar3.org/docs/releases) with the `relx` tool, providing a way to ship fully self-contained Erlang systems. Release update scripts for live code updates can also be generated. | +| Shell | A full shell with your applications available can be started with `rebar3 shell`. From there, call tasks as `r3:do(compile)` to automatically recompile and reload the code without interruption | +| Tarballs | Releases can be packaged into tarballs ready to be deployed. | +| Templates | Configurable templates ship out of the box (try `rebar3 new` for a list or `rebar3 new help <template>` for a specific one). [Custom templates](http://www.rebar3.org/docs/using-templates) are also supported, and plugins can also add their own. | +| Unstable namespace | We use a namespace to provide commands that are still in flux, allowing to test more experimental features we are working on. See `rebar3 unstable`. | +| Xref | Run cross reference analysis on the project with [xref](http://www.erlang.org/doc/apps/tools/xref_chapter.html) by calling `rebar3 xref`. | + +## Migrating From rebar2 + +The grievances we had with Rebar 2.x were not fixable without breaking +compatibility in some very important ways. + +A full guide titled [From Rebar 2.x to Rebar3](http://www.rebar3.org/docs/from-rebar-2x-to-rebar3) +is provided on the documentation website. + +Notable modifications include mandating a more standard set of directory +structures, changing the handling of dependencies, moving some compilers (such +as C, Diameter, ErlyDTL, or ProtoBuffs) to +[plugins](http://www.rebar3.org/docs/using-available-plugins) rather than +maintaining them in core rebar, and moving release builds from reltool to +relx. + +## Additional Resources In case of problems that cannot be solved through documentation or examples, you may want to try to contact members of the community for help. The community is @@ -180,3 +155,5 @@ General rebar community resources and links: - #rebar on [irc.freenode.net](http://freenode.net/) - [issues](https://github.com/rebar/rebar3/issues) - [Documentation](http://www.rebar3.org/v3.0/docs) + +To contribute to rebar3, please refer to [CONTRIBUTING](CONTRIBUTING.md). |