SisMaker
/
rebar3
1
0
Fork 0
Code Issues 0 Pull Requests 0 Projects 0 Releases 62 Wiki Activity
Browse Source

Rework README and CONTRIBUTING documents 

- The README is better targetted to newcomers and explains the basics of
  the project: what it is, why use it, how to get started, where to find
  more information. It looks less like a reference and more like a brief
  overview of rebar3.
- Whatever looks like a list or reference manual material is expected to
  be moved to the website
- Be clearer about the rebar3 project structure in CONTRIBUTING.md;
  explain how to write tests, how to structure code, and so on.
- Added contributing section on bug reports, feature requests, etc.
pull/1023/head
Fred Hebert 9 years ago
parent
c8e0b1c5ce
commit
63a334a78b
2 changed files with 409 additions and 239 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +282
    -89
      CONTRIBUTING.md
  2. +127
    -150
      README.md

+ 282
- 89
CONTRIBUTING.md View File

@ -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.

+ 127
- 150
README.md View File

@ -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
[![Build Status](https://travis-ci.org/rebar/rebar3.svg?branch=master)](https://travis-ci.org/rebar/rebar3) [![Windows build status](https://ci.appveyor.com/api/projects/status/yx4oitd9pvd2kab3?svg=true)](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).

Write Preview
Loading…
Cancel
Save