From 63a334a78b7036d5c1bbc35065de1451778377a0 Mon Sep 17 00:00:00 2001 From: Fred Hebert Date: Sun, 17 Jan 2016 10:11:15 -0500 Subject: 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. --- README.md | 277 ++++++++++++++++++++++++++++---------------------------------- 1 file changed, 127 insertions(+), 150 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index cddb843..65f9284 100644 --- a/README.md +++ b/README.md @@ -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 ,,...,`. | +| 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 `). 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 `, 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