From e9032fa19c9d7981134e519256a4d934d2c4e5d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sun, 3 Apr 2016 17:50:26 +0200 Subject: Update user guide --- guide/asciidoc.html | 9 ++++++--- guide/contributing.html | 4 +++- guide/deps.html | 2 +- guide/getting_started.html | 17 +++++++++++++---- guide/index.html | 2 +- guide/plugins_list.html | 7 ++++--- 6 files changed, 28 insertions(+), 13 deletions(-) (limited to 'guide') diff --git a/guide/asciidoc.html b/guide/asciidoc.html index ed4222b..c24810f 100644 --- a/guide/asciidoc.html +++ b/guide/asciidoc.html @@ -35,7 +35,10 @@ div.navfooter{margin-bottom:1em}
Prev   Next

Chapter 12. AsciiDoc documentation

Erlang.mk provides rules for generating documentation from AsciiDoc files. It can automatically build a user guide PDF, -chunked HTML documentation and Unix manual pages.

12.1. Writing AsciiDoc documentation

AsciiDoc is a text document format for +chunked HTML documentation and Unix manual pages.

12.1. Requirements

It is necessary to have AsciiDoc, +xsltproc and +dblatex installed on your +system for Erlang.mk to generate documentation from AsciiDoc sources.

12.2. Writing AsciiDoc documentation

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

The AsciiDoc user guide @@ -45,8 +48,8 @@ file is doc/src/guide/ for the user guide, and doc/src/manual/ for the function reference. In the case of the user guide, the entry point is always doc/src/guide/book.asciidoc.

For manual pages, it is good practice to use section 3 for -modules, and section 7 for the application itself.

12.2. Configuration

All of the AsciiDoc related configuration can be done directly -inside the files themselves.

12.3. Usage

To build all documentation:

$ make docs

To build only the AsciiDoc documentation:

$ make asciidoc

To build only the user guide:

$ make asciidoc-guide

To build only the manual:

$ make asciidoc-manual

To install man pages on Unix:

$ make install-docs

Erlang.mk allows customizing the installation path and sections +modules, and section 7 for the application itself.

12.3. Configuration

All of the AsciiDoc related configuration can be done directly +inside the files themselves.

12.4. Usage

To build all documentation:

$ make docs

To build only the AsciiDoc documentation:

$ make asciidoc

To build only the user guide:

$ make asciidoc-guide

To build only the manual:

$ make asciidoc-manual

To install man pages on Unix:

$ make install-docs

Erlang.mk allows customizing the installation path and sections of the man pages to be installed. The MAN_INSTALL_PATH variable defines where man pages will be installed. It defaults to /usr/local/share/man. The MAN_SECTIONS variable defines diff --git a/guide/contributing.html b/guide/contributing.html index 43728ec..0c49ce3 100644 --- a/guide/contributing.html +++ b/guide/contributing.html @@ -78,7 +78,9 @@ You can of course speed things up using the -j and make summary to know what changed since the previous run.

25.5. Documentation

The documentation is always right.

If you think you have found a mistake in the documentation, this is a bug. You can either open a ticket or send a pull request.

To make sure that the documentation changes work, install -Asciidoc on your system and run make docs.

25.6. Feature requests

If you have an awesome idea or need something that Erlang.mk +the listed Requirements +Chapter 12, AsciiDoc documentation on your system and +run make docs.

25.6. Feature requests

If you have an awesome idea or need something that Erlang.mk doesn’t provide yet, open a ticket. Provide as much detail as possible.

If you have code, great! Open a pull request as previously explained.

If not, you can still improve your feature request by writing diff --git a/guide/deps.html b/guide/deps.html index cd00de4..b10cfe6 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -154,7 +154,7 @@ if you know you will never use this project as a dependency, = will work. But to avoid it biting you later on, do this:

DEPS_DIR ?= $(CURDIR)/libs

The $(CURDIR) part is important, otherwise dependencies of dependencies will be fetched in the wrong directory.

Erlang.mk will also export the REBAR_DEPS_DIR variable for compatibility with Rebar build tools, as long as they are -recent enough.

7.6. Dependencies local to the repository

In addition to the dependencies that are fetched, Erlang.mk +recent enough.

7.6. Many applications in one repository

In addition to the dependencies that are fetched, Erlang.mk also allows you to have dependencies local to your repository. This kind of layout is sometimes called multi-application repositories, or repositories with multiple applications.

They work exactly the same as remote dependencies, except:

  • diff --git a/guide/getting_started.html b/guide/getting_started.html index b34b6e0..1d63499 100644 --- a/guide/getting_started.html +++ b/guide/getting_started.html @@ -115,13 +115,22 @@ heart_beat_kill_pid = 16389 Erlang/OTP 18 [erts-7.0] [source] [64-bit] [smp:4:4] [async-threads:10] [hipe] [kernel-poll:false] Eshell V7.0 (abort with ^G) -(hello_joe@127.0.0.1)1>

    Simple as that!

2.6. Using spaces instead of tabs

Erlang.mk defaults to tabs when creating files from templates. +(hello_joe@127.0.0.1)1>

Simple as that!

2.6. Getting started from scratch

If you already have an application, or you want to have full +control over what files will be created, you can setup Erlang.mk +manually.

Erlang.mk is very easy to setup: all that you need to do is to +create a folder, put Erlang.mk in it, and write a one line +Makefile containing:

include erlang.mk

For a step by step:

$ mkdir hello_joe
+$ cd hello_joe
+$ curl https://raw.githubusercontent.com/ninenines/erlang.mk/master/erlang.mk
+$ echo "include erlang.mk" > Makefile
+$ make

From that point onward you can create an src/ folder or start +using templates.

2.7. Using spaces instead of tabs

Erlang.mk defaults to tabs when creating files from templates. This is in part because of a personal preference, and in part because it is much easier to convert tabs to spaces than the opposite.

Use the SP variable if you prefer spaces. Set it to the number of spaces per indentation level you want.

For example, if you prefer two spaces per indentation level:

$ make -f erlang.mk bootstrap SP=2

When you bootstrap the project initially, the variable automatically gets added to the Makefile, so you only need to provide it when -you get started.

2.7. Using templates

It is no secret that Erlang’s OTP behaviors tend to have some +you get started.

2.8. Using templates

It is no secret that Erlang’s OTP behaviors tend to have some boilerplate. It is rarely an issue of course, except when creating new modules. That’s why Erlang.mk not only comes with templates for generating projects, but also individual modules!

You can list all available templates with the list-templates @@ -132,12 +141,12 @@ using the gen_server template.

This module is make:

$ make
  ERLC   my_server.erl
  APP    hello_joe.app.src

All that’s left to do is to open it in your favorite editor -and make it do something!

2.8. Hiding Erlang.mk from git

Erlang.mk is a large text file. It can easily take a large part of +and make it do something!

2.9. Hiding Erlang.mk from git

Erlang.mk is a large text file. It can easily take a large part of a git diff or a git grep command. You can avoid this by telling Git that erlang.mk is a binary file.

Add this to your .gitattributes file. This is a file that you can create at the root of your repository:

erlang.mk -diff

The erlang.mk file will still appear in diffs and greps, but as a binary file, meaning its contents won’t be shown by default -anymore.

2.9. Getting help

During development, if you don’t remember the name of a target, +anymore.

2.10. Getting help

During development, if you don’t remember the name of a target, you can always run make help:

$ make help
 erlang.mk (version 1.2.0-642-gccd2b9f) is distributed under the terms of the ISC License.
 Copyright (c) 2013-2015 Loïc Hoguin <essen@ninenines.eu>
diff --git a/guide/index.html b/guide/index.html
index 592def3..a2c8d00 100644
--- a/guide/index.html
+++ b/guide/index.html
@@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
 
 

 
-
   Next
Erlang.mk User Guide
Loïc Hoguin
Table of Contents
1. Installation
1.1. On Unix
1.2. On Windows
2. Getting started
2.1. Creating a folder for your project
2.2. Downloading Erlang.mk
2.3. Getting started with OTP applications
2.4. Getting started with OTP libraries
2.5. Getting started with OTP releases
2.6. Using spaces instead of tabs
2.7. Using templates
2.8. Hiding Erlang.mk from git
2.9. Getting help
3. Overview
3.1. Building your project
3.2. Exploring the package index
3.3. Generating documentation
3.4. Running tests
3.5. Need more?
4. Updating Erlang.mk
4.1. Initial bootstrap
4.2. Updating
4.3. Customizing the build
5. Limitations
5.1. Erlang must be available
5.2. Spaces in path
5.3. Dependency tracking and modification times
I. Code
6. Building
6.1. How to build
6.2. What to build
6.3. Application resource file
6.4. Automatic application resource file values
6.5. File formats
6.6. Compilation options
6.7. Cold and hot builds
6.8. Dependency tracking
6.9. Generating Erlang source
6.10. Cleaning
7. Packages and dependencies
7.1. Searching packages
7.2. Adding dependencies to your project
7.3. How deps are fetched and built
7.4. Ignoring unwanted dependencies
7.5. Dependencies directory
7.6. Dependencies local to the repository
7.7. Repositories with no application at the root level
7.8. Autopatch
7.9. Skipping deps
8. NIFs and port drivers
8.1. C source code location and Erlang environment
8.2. Using a custom Makefile
8.3. Using Erlang.mk directly
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
10. Escripts
11. Compatibility with other build tools
11.1. Rebar projects as Erlang.mk dependencies
11.2. Erlang.mk projects as Rebar dependencies
II. Documentation
12. AsciiDoc documentation
12.1. Writing AsciiDoc documentation
12.2. Configuration
12.3. Usage
13. EDoc comments
13.1. Writing EDoc comments
13.2. Configuration
13.3. Usage
III. Tests
14. Erlang shell
14.1. Configuration
14.2. Usage
15. EUnit
15.1. Writing tests
15.2. Configuration
15.3. Usage
16. Common Test
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Code coverage
18. Continuous integration
19. Dialyzer
19.1. How it works
19.2. Configuration
19.3. Usage
20. Xref
IV. Third-party plugins
21. External plugins
21.1. Loading all plugins from a dependency
21.2. Loading one plugin from a dependency
21.3. Writing external plugins
22. List of plugins
22.1. efene.mk
22.2. elixir.mk
22.3. elvis.mk
22.4. geas
22.5. hexer.mk
22.6. lfe.mk
22.7. mix.mk
22.8. reload.mk
V. About Erlang.mk
23. Why Erlang.mk
23.1. Erlang.mk is fast
23.2. Erlang.mk gives you the full power of Unix
23.3. Erlang.mk is a text file
23.4. Erlang.mk can manage Erlang itself
23.5. Erlang.mk can do more than Erlang
23.6. Erlang.mk integrates nicely in Make and Automake projects
24. Short history
24.1. Before Erlang.mk
24.2. Lifetime of the project
25. Contributing
25.1. Priorities
25.2. Bugs
25.3. Code
25.4. Packages
25.5. Documentation
25.6. Feature requests
   Next

+
   Next
Erlang.mk User Guide
Loïc Hoguin
Table of Contents
1. Installation
1.1. On Unix
1.2. On Windows
2. Getting started
2.1. Creating a folder for your project
2.2. Downloading Erlang.mk
2.3. Getting started with OTP applications
2.4. Getting started with OTP libraries
2.5. Getting started with OTP releases
2.6. Getting started from scratch
2.7. Using spaces instead of tabs
2.8. Using templates
2.9. Hiding Erlang.mk from git
2.10. Getting help
3. Overview
3.1. Building your project
3.2. Exploring the package index
3.3. Generating documentation
3.4. Running tests
3.5. Need more?
4. Updating Erlang.mk
4.1. Initial bootstrap
4.2. Updating
4.3. Customizing the build
5. Limitations
5.1. Erlang must be available
5.2. Spaces in path
5.3. Dependency tracking and modification times
I. Code
6. Building
6.1. How to build
6.2. What to build
6.3. Application resource file
6.4. Automatic application resource file values
6.5. File formats
6.6. Compilation options
6.7. Cold and hot builds
6.8. Dependency tracking
6.9. Generating Erlang source
6.10. Cleaning
7. Packages and dependencies
7.1. Searching packages
7.2. Adding dependencies to your project
7.3. How deps are fetched and built
7.4. Ignoring unwanted dependencies
7.5. Dependencies directory
7.6. Many applications in one repository
7.7. Repositories with no application at the root level
7.8. Autopatch
7.9. Skipping deps
8. NIFs and port drivers
8.1. C source code location and Erlang environment
8.2. Using a custom Makefile
8.3. Using Erlang.mk directly
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
10. Escripts
11. Compatibility with other build tools
11.1. Rebar projects as Erlang.mk dependencies
11.2. Erlang.mk projects as Rebar dependencies
II. Documentation
12. AsciiDoc documentation
12.1. Requirements
12.2. Writing AsciiDoc documentation
12.3. Configuration
12.4. Usage
13. EDoc comments
13.1. Writing EDoc comments
13.2. Configuration
13.3. Usage
III. Tests
14. Erlang shell
14.1. Configuration
14.2. Usage
15. EUnit
15.1. Writing tests
15.2. Configuration
15.3. Usage
16. Common Test
16.1. Writing tests
16.2. Configuration
16.3. Usage
17. Code coverage
18. Continuous integration
19. Dialyzer
19.1. How it works
19.2. Configuration
19.3. Usage
20. Xref
IV. Third-party plugins
21. External plugins
21.1. Loading all plugins from a dependency
21.2. Loading one plugin from a dependency
21.3. Writing external plugins
22. List of plugins
22.1. efene.mk
22.2. elixir.mk
22.3. elvis.mk
22.4. geas
22.5. hexer.mk
22.6. jorel
22.7. lfe.mk
22.8. mix.mk
22.9. reload.mk
V. About Erlang.mk
23. Why Erlang.mk
23.1. Erlang.mk is fast
23.2. Erlang.mk gives you the full power of Unix
23.3. Erlang.mk is a text file
23.4. Erlang.mk can manage Erlang itself
23.5. Erlang.mk can do more than Erlang
23.6. Erlang.mk integrates nicely in Make and Automake projects
24. Short history
24.1. Before Erlang.mk
24.2. Lifetime of the project
25. Contributing
25.1. Priorities
25.2. Bugs
25.3. Code
25.4. Packages
25.5. Documentation
25.6. Feature requests
   Next

 

 
 
diff --git a/guide/plugins_list.html b/guide/plugins_list.html
index b05e43a..ddbfcbb 100644
--- a/guide/plugins_list.html
+++ b/guide/plugins_list.html
@@ -41,11 +41,12 @@ language for the BEAM.
Erlang style reviewer.

22.4. geas

Geas gives aggregated information on a project and its dependencies, and is available as an Erlang.mk plugin.

22.5. hexer.mk

An Hex plugin for Erlang.mk. -Hex is a package manager for the Elixir ecosystem.

22.6. lfe.mk

An LFE plugin for Erlang.mk. +Hex is a package manager for the Elixir ecosystem.

22.6. jorel

Jorel is Just anOther RELease +assembler for Erlang/OTP, and is available as an Erlang.mk plugin.

22.7. lfe.mk

An LFE plugin for Erlang.mk. LFE, or Lisp Flavoured Erlang, is an alternative -language for the BEAM.

22.7. mix.mk

A Mix plugin for Erlang.mk, +language for the BEAM.

22.8. mix.mk

A Mix plugin for Erlang.mk, to generate a compatible configuration file for -Mix.

22.8. reload.mk

A live reload plugin for Erlang.mk.

Prev Up Next
 Home 
+Mix.

22.9. reload.mk

A live reload plugin for Erlang.mk.

Prev Up Next
 Home 
-- cgit v1.2.3