From b158218b498c0ef4f4019a6e6ff21189643d5476 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 30 Dec 2015 17:23:39 +0100 Subject: Update user guide --- guide/about.html | 2 +- guide/contributing.html | 12 ++++++------ guide/history.html | 6 +++--- guide/index.html | 2 +- guide/overview.html | 8 ++++---- guide/plugins_list.html | 44 ++++++++++++++++++++++++++++++++++++++++++++ guide/plugins_usage.html | 4 ++-- guide/why.html | 14 +++++++------- 8 files changed, 68 insertions(+), 24 deletions(-) create mode 100644 guide/plugins_list.html diff --git a/guide/about.html b/guide/about.html index 44a00fb..0157a98 100644 --- a/guide/about.html +++ b/guide/about.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-

Part V. About Erlang.mk

+

Part V. About Erlang.mk

diff --git a/guide/contributing.html b/guide/contributing.html index 43728ec..76c22e3 100644 --- a/guide/contributing.html +++ b/guide/contributing.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-

Chapter 25. Contributing

You are welcome and encouraged to contribute.

This is how.

25.1. Priorities

From the most important to the least important:

  • +

    Chapter 26. Contributing

    You are welcome and encouraged to contribute.

    This is how.

    26.1. Priorities

    From the most important to the least important:

    • Bugs
    • Package issues/additions @@ -41,7 +41,7 @@ Package issues/additions Refactoring
    • Features -

    25.2. Bugs

    If you have found a bug, you should open a ticket. Include +

26.2. Bugs

If you have found a bug, you should open a ticket. Include everything relevant including the command you used, output, a link to the code that triggers the issue, why you think this is a bug, etc.

If you think you have found a bug but you are not sure, you @@ -49,7 +49,7 @@ should open a ticket as previously explained.

If you have found a bug and NOW, open a ticket as previously explained.

Once you have opened a ticket, be patient, try to answer questions in a timely manner and confirm that the bug was indeed fixed when it is.

If you can’t be patient, either try to solve the bug and -contribute the fix back or become a paying customer.

25.3. Code

The code is located in the core/*.mk and plugins/*.mk files. +contribute the fix back or become a paying customer.

26.3. Code

The code is located in the core/*.mk and plugins/*.mk files. The tests are located in the test/Makefile and test/*.mk files.

If you have a fix or a hack for a bug, you should open a pull request. Any fix should include a test case that fails before the fix and is working after.

If you have a test case that reproduces a bug, but no fix for @@ -62,7 +62,7 @@ The value 4 is particular and shows expanded commands right before they are executed.

To run tests in parallel, use the -j option. It is generally a good idea to also use the -k option to run all tests even if one fails. For example: make check -j 32 -k.

Some changes should be tested against all packages. Continue -reading for more details on testing them.

25.4. Packages

You can search existing packages using the make search q=STRING +reading for more details on testing them.

26.4. Packages

You can search existing packages using the make search q=STRING command. This can be done both from an Erlang.mk project or directly from the Erlang.mk repository.

Packages can be added to the index using the pkg_add.sh script.

$ git clone https://github.com/$YOURUSERNAME/erlang.mk
 $ cd erlang.mk
@@ -75,10 +75,10 @@ where PACKAGE is the name of the package, for examp
 This can take a long time. Some packages will fail with certain
 versions of Erlang, or if a prerequisite is missing from your system.
 You can of course speed things up using the -j and -k flags.

After all packages have been tested, you can run the command -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, +make summary to know what changed since the previous run.

26.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 +Asciidoc on your system and run make docs.

26.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/history.html b/guide/history.html index 8ccb762..820aff3 100644 --- a/guide/history.html +++ b/guide/history.html @@ -33,8 +33,8 @@ div.navfooter{margin-bottom:1em}

-

Chapter 24. Short history

This chapter aims to be a brief record of the life of the -Erlang.mk project.

24.1. Before Erlang.mk

Erlang.mk originates from the Cowboy project. Cowboy started +

Chapter 25. Short history

This chapter aims to be a brief record of the life of the +Erlang.mk project.

25.1. Before Erlang.mk

Erlang.mk originates from the Cowboy project. Cowboy started as a Rebar project and I, Loïc Hoguin, was very happy with it for a couple years. Over time however I started getting annoyed and frustrated by a number of things, including bad defaults, @@ -46,7 +46,7 @@ than a minute to complete.

Following this success I started removing a lit on the fateful day of January 5th, 2013, removed the dependency on Rebar entirely. Rebar, and in particular the concept of dependencies, was, and still is, a pretty strong influence.

Erlang.mk was conceived.

A few months passed and, on May 1st, 2013, the Erlang.mk -repository was created. Erlang.mk was born.

Little did I know how much it would grow.

24.2. Lifetime of the project

Erlang.mk would eventually become a much larger file able to +repository was created. Erlang.mk was born.

Little did I know how much it would grow.

25.2. Lifetime of the project

Erlang.mk would eventually become a much larger file able to deal with many more projects than just Cowboy. From the birth of the project, the biggest force for growth was user contributions, because Erlang.mk appealed to a variety of people with different diff --git a/guide/index.html b/guide/index.html index afe5cf2..347e741 100644 --- a/guide/index.html +++ b/guide/index.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}

-

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. 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
13. EDoc comments
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. Property based testing
18. Code coverage
19. Continuous integration
20. Dialyzer
20.1. How it works
20.2. Configuration
20.3. Usage
21. Xref
IV. Third-party plugins
22. External plugins
22.1. Loading all plugins from a dependency
22.2. Loading one plugin from a dependency
22.3. Writing external plugins
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
+

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. 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
13. EDoc comments
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. Property based testing
18. Code coverage
19. Continuous integration
20. Dialyzer
20.1. How it works
20.2. Configuration
20.3. Usage
21. Xref
IV. Third-party plugins
22. External plugins
22.1. Loading all plugins from a dependency
22.2. Loading one plugin from a dependency
22.3. Writing external plugins
23. List of plugins
23.1. elvis.mk
23.2. geas
23.3. hexer.mk
23.4. reload.mk
V. About Erlang.mk
24. Why Erlang.mk
24.1. Erlang.mk is fast
24.2. Erlang.mk gives you the full power of Unix
24.3. Erlang.mk is a text file
24.4. Erlang.mk can manage Erlang itself
24.5. Erlang.mk can do more than Erlang
24.6. Erlang.mk integrates nicely in Make and Automake projects
25. Short history
25.1. Before Erlang.mk
25.2. Lifetime of the project
26. Contributing
26.1. Priorities
26.2. Bugs
26.3. Code
26.4. Packages
26.5. Documentation
26.6. Feature requests
diff --git a/guide/overview.html b/guide/overview.html index 3357c3d..fb5ac33 100644 --- a/guide/overview.html +++ b/guide/overview.html @@ -81,10 +81,10 @@ support for Chapter 20, Dialyzer and Xref Chapter 21, Xref, to perform success typing analysis and cross referencing -of the code.

3.5. Need more?

Not convinced yet? You can read about why you should use Erlang.mk -Chapter 23, Why Erlang.mk -and its history -Chapter 24, Short history. And if you’re still not +of the code.

3.5. Need more?

Not convinced yet? You can read about why you should use Erlang.mk +Chapter 24, Why Erlang.mk +and its history +Chapter 25, Short history. And if you’re still not convinced after that, it’s OK! The world would be boring if everyone agreed on everything all the time.

diff --git a/guide/plugins_list.html b/guide/plugins_list.html new file mode 100644 index 0000000..a14ac77 --- /dev/null +++ b/guide/plugins_list.html @@ -0,0 +1,44 @@ + + + + +Erlang.mk User Guide + + + +
+ + + +
+
+ +

Chapter 23. List of plugins

This is a non-exhaustive list of Erlang.mk plugins, sorted +alphabetically.

23.1. elvis.mk

An Elvis plugin for Erlang.mk. +Elvis is an Erlang style reviewer.

23.2. geas

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

23.3. hexer.mk

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

23.4. reload.mk

A live reload plugin for Erlang.mk.

+
+ + diff --git a/guide/plugins_usage.html b/guide/plugins_usage.html index eaac4f9..e45f59d 100644 --- a/guide/plugins_usage.html +++ b/guide/plugins_usage.html @@ -33,7 +33,7 @@ div.navfooter{margin-bottom:1em}
-

Chapter 22. External plugins

It is often convenient to be able to keep the build files +

Chapter 22. External plugins

It is often convenient to be able to keep the build files used by all your projects in one place. Those files could be Makefiles, configuration files, templates and more.

Erlang.mk allows you to automatically load plugins from dependencies. Plugins can do anything, including defining @@ -65,7 +65,7 @@ file:

THIS := $(dir $(realpath $(lastword $(MAKEF
 include $(THIS)/mk/dist.mk
 include $(THIS)/mk/templates.mk

The THIS variable is required to relatively include files.

This allows users to not only be able to select individual plugins, but also select all plugins from the dependency -in one go if they wish to do so.

+in one go if they wish to do so.

diff --git a/guide/why.html b/guide/why.html index 925063c..5dfa60e 100644 --- a/guide/why.html +++ b/guide/why.html @@ -33,15 +33,15 @@ div.navfooter{margin-bottom:1em}
-

Chapter 23. Why Erlang.mk

Why would you choose Erlang.mk, if not for its +

Chapter 24. Why Erlang.mk

Why would you choose Erlang.mk, if not for its many features Chapter 3, Overview? This chapter will -attempt to answer that.

23.1. Erlang.mk is fast

Erlang.mk is as fast as it gets.

Erlang.mk will group the compilation of files so as to avoid +attempt to answer that.

24.1. Erlang.mk is fast

Erlang.mk is as fast as it gets.

Erlang.mk will group the compilation of files so as to avoid running the BEAM more than necessary. This saves many seconds compared to traditional Makefiles, even on small projects.

Erlang.mk will not try to be too smart. It provides a simple solution that works for most people, and gives additional options for projects that run into edge cases, often in the -form of extra variables or rules to be defined.

23.2. Erlang.mk gives you the full power of Unix

Erlang.mk is a Makefile.

You could use Erlang.mk directly without configuring anything +form of extra variables or rules to be defined.

24.2. Erlang.mk gives you the full power of Unix

Erlang.mk is a Makefile.

You could use Erlang.mk directly without configuring anything and it would just work. But you can also extend it greatly either through configuration or hooks, and you can of course add your own rules to the Makefile.

In all cases: for configuration, hooks or custom rules, you @@ -49,22 +49,22 @@ have all the power of Unix at your disposal, and can call any utility or even any language interpreter you want, every time you need to. Erlang.mk also allows you to write scripts in this small language called Erlang directly inside -your Makefile if you ever need to…

23.3. Erlang.mk is a text file

Erlang.mk is a Makefile.

Which means Erlang.mk is a simple text file. You can edit a +your Makefile if you ever need to…

24.3. Erlang.mk is a text file

Erlang.mk is a Makefile.

Which means Erlang.mk is a simple text file. You can edit a text file. Nothing stops you. If you run into any bug, or behavior that does not suit you, you can just open the erlang.mk file in your favorite editor, fix and/or comment -a few lines, save, and try again. It’s as simple as it gets.

Currently using a binary build tool? Good luck with that.

23.4. Erlang.mk can manage Erlang itself

Erlang.mk isn’t written in Erlang.

That’s not a good thing, you say? Well, here’s one thing +a few lines, save, and try again. It’s as simple as it gets.

Currently using a binary build tool? Good luck with that.

24.4. Erlang.mk can manage Erlang itself

Erlang.mk isn’t written in Erlang.

That’s not a good thing, you say? Well, here’s one thing that Erlang.mk and Makefiles can do for you that Erlang build tool can’t easily: choose what version of Erlang is to be used for compiling the project.

This really is a one-liner in Erlang.mk (a few more lines if you also let it download and build Erlang directly) and allows for even greater things, like testing your project across all supported Erlang versions in one small -command: make -k ci.

23.5. Erlang.mk can do more than Erlang

Erlang.mk doesn’t care what your dependencies are written in.

Erlang.mk will happily compile any dependency, as long as +command: make -k ci.

24.5. Erlang.mk can do more than Erlang

Erlang.mk doesn’t care what your dependencies are written in.

Erlang.mk will happily compile any dependency, as long as they come with a Makefile. The dependency can be written in C, C++ or even Javascript… Who cares, really? If you need Erlang.mk to fetch it, then Erlang.mk will fetch it -and compile it as needed.

23.6. Erlang.mk integrates nicely in Make and Automake projects

If you are planning to put your project in the middle of +and compile it as needed.

24.6. Erlang.mk integrates nicely in Make and Automake projects

If you are planning to put your project in the middle of a Make or Automake-based build environment, then the most logical thing to do is to use a Makefile.

Erlang.mk will happily sit in such an environment and behave as you expect it to.

-- cgit v1.2.3