From c730de793f32ccd58dba04901310a8cc1cb6c54a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 27 Nov 2024 12:16:07 +0100 Subject: Update user guide --- guide/getting_started.html | 12 +++++++++++- guide/index.html | 2 +- guide/plugins_usage.html | 20 +++++++++++++++++--- 3 files changed, 29 insertions(+), 5 deletions(-) diff --git a/guide/getting_started.html b/guide/getting_started.html index 7369da2..8d4d0e9 100644 --- a/guide/getting_started.html +++ b/guide/getting_started.html @@ -142,7 +142,17 @@ 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 target:

$ make list-templates
-Available templates: cowboy_http cowboy_loop cowboy_rest cowboy_ws gen_fsm gen_server gen_statem ranch_protocol supervisor

To generate a module, let’s say a gen_server, all you need to +Available templates: + cowboy_http_h + cowboy_loop_h + cowboy_rest_h + cowboy_websocket_h + gen_fsm + gen_server + gen_statem + module + ranch_protocol + supervisor

To generate a module, let’s say a gen_server, all you need to do is to call make new with the appropriate arguments:

$ make new t=gen_server n=my_server

This will create a module located in src/my_server.erl using the gen_server template.

This module is automatically compiled the next time you run make:

$ make
diff --git a/guide/index.html b/guide/index.html
index 2730877..9d88626 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. 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. Fetching and listing dependencies only
7.5. Querying dependencies
7.6. Ignoring unwanted dependencies
7.7. Dependencies directory
7.8. Many applications in one repository
7.9. Repositories with no application at the root level
7.10. Autopatch
7.11. Dealing with duplicate modules
7.12. 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
8.4. Propagating compile and linker flags to sub-Makefiles
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
9.6. Getting Relx semver value
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
11.1. Requirements
11.2. Generating an escript
11.3. Configuration
11.4. Extra files
11.5. Optimizing for size
12. OTP version management
12.1. Erlang versions
12.2. OTP version pinning
12.3. Continuous integration
12.4. Configuring Kerl
13. Cross compiling
13.1. Compiling
13.2. Building the release
14. Compatibility with other build tools
14.1. Rebar projects as Erlang.mk dependencies
14.2. Erlang.mk projects as Rebar dependencies
II. Documentation
15. AsciiDoc documentation
15.1. Requirements
15.2. Writing AsciiDoc documentation
15.3. Configuration
15.4. Usage
16. EDoc comments
16.1. Writing EDoc comments
16.2. Configuration
16.3. Usage
16.4. Running EDoc on all applications
17. Sphinx documentation
17.1. Writing Sphinx documentation
17.2. Basic setup
17.3. Erlang.mk configuration
17.4. Generating man pages
III. Tests
18. Erlang shell
18.1. Configuration
18.2. Usage
19. EUnit
19.1. Writing tests
19.2. Configuration
19.3. Usage
20. Common Test
20.1. Writing tests
20.2. Configuration
20.3. Usage
21. PropEr
22. Triq
23. Code coverage
23.1. Enabling cover when running tests
23.2. Adding applications to the cover report
23.3. Removing modules from the cover report
23.4. Configuring paths
23.5. Merging coverdata files
24. Continuous integration
24.1. Configuring Erlang/OTP versions to test
24.2. Running tests across all configured versions
24.3. Extending the CI targets
25. Dialyzer
25.1. How it works
25.2. Configuration
25.3. Usage
25.4. Dialyzing beam files
26. Concuerror
26.1. Configuration
26.2. Writing tests
26.3. Usage
27. Xref
27.1. Usage
27.2. Queries
27.3. Analysis scope
27.4. Ignoring warnings
IV. Third-party plugins
28. External plugins
28.1. Loading all plugins from a dependency
28.2. Loading one plugin from a dependency
28.3. Writing external plugins
28.4. Early-stage plugins
28.5. Loading  plugins local to the application
29. List of plugins
29.1. ci.erlang.mk
29.2. efene.mk
29.3. elixir.mk
29.4. elvis.mk
29.5. esh.mk
29.6. geas
29.7. hexer.mk
29.8. hexpm.mk
29.9. jorel
29.10. lfe.mk
29.11. mix.mk
29.12. reload.mk
29.13. rust.mk
29.14. version.mk
V. About Erlang.mk
30. Why Erlang.mk
30.1. Erlang.mk is fast
30.2. Erlang.mk gives you the full power of Unix
30.3. Erlang.mk is a text file
30.4. Erlang.mk can manage Erlang itself
30.5. Erlang.mk can do more than Erlang
30.6. Erlang.mk integrates nicely in Make and Automake projects
31. Short history
31.1. Before Erlang.mk
31.2. Lifetime of the project
32. Contributing
32.1. Priorities
32.2. Bugs
32.3. Code
32.4. Packages
32.5. Documentation
32.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. Fetching and listing dependencies only
7.5. Querying dependencies
7.6. Ignoring unwanted dependencies
7.7. Dependencies directory
7.8. Many applications in one repository
7.9. Repositories with no application at the root level
7.10. Autopatch
7.11. Dealing with duplicate modules
7.12. 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
8.4. Propagating compile and linker flags to sub-Makefiles
9. Releases
9.1. Setup
9.2. Configuration
9.3. Generating the release
9.4. Running the release
9.5. Upgrading a release
9.6. Getting Relx semver value
10. Self-extracting releases
10.1. Generating the self-extracting archive
10.2. Running the release
11. Escripts
11.1. Requirements
11.2. Generating an escript
11.3. Configuration
11.4. Extra files
11.5. Optimizing for size
12. OTP version management
12.1. Erlang versions
12.2. OTP version pinning
12.3. Continuous integration
12.4. Configuring Kerl
13. Cross compiling
13.1. Compiling
13.2. Building the release
14. Compatibility with other build tools
14.1. Rebar projects as Erlang.mk dependencies
14.2. Erlang.mk projects as Rebar dependencies
II. Documentation
15. AsciiDoc documentation
15.1. Requirements
15.2. Writing AsciiDoc documentation
15.3. Configuration
15.4. Usage
16. EDoc comments
16.1. Writing EDoc comments
16.2. Configuration
16.3. Usage
16.4. Running EDoc on all applications
17. Sphinx documentation
17.1. Writing Sphinx documentation
17.2. Basic setup
17.3. Erlang.mk configuration
17.4. Generating man pages
III. Tests
18. Erlang shell
18.1. Configuration
18.2. Usage
19. EUnit
19.1. Writing tests
19.2. Configuration
19.3. Usage
20. Common Test
20.1. Writing tests
20.2. Configuration
20.3. Usage
21. PropEr
22. Triq
23. Code coverage
23.1. Enabling cover when running tests
23.2. Adding applications to the cover report
23.3. Removing modules from the cover report
23.4. Configuring paths
23.5. Merging coverdata files
24. Continuous integration
24.1. Configuring Erlang/OTP versions to test
24.2. Running tests across all configured versions
24.3. Extending the CI targets
25. Dialyzer
25.1. How it works
25.2. Configuration
25.3. Usage
25.4. Dialyzing beam files
26. Concuerror
26.1. Configuration
26.2. Writing tests
26.3. Usage
27. Xref
27.1. Usage
27.2. Queries
27.3. Analysis scope
27.4. Ignoring warnings
IV. Third-party plugins
28. External plugins
28.1. Loading all plugins from a dependency
28.2. Loading one plugin from a dependency
28.3. Writing external plugins
28.4. Early-stage plugins
28.5. Loading plugins local to the application
28.6. Adding templates via plugins
29. List of plugins
29.1. ci.erlang.mk
29.2. efene.mk
29.3. elixir.mk
29.4. elvis.mk
29.5. esh.mk
29.6. geas
29.7. hexer.mk
29.8. hexpm.mk
29.9. jorel
29.10. lfe.mk
29.11. mix.mk
29.12. reload.mk
29.13. rust.mk
29.14. version.mk
V. About Erlang.mk
30. Why Erlang.mk
30.1. Erlang.mk is fast
30.2. Erlang.mk gives you the full power of Unix
30.3. Erlang.mk is a text file
30.4. Erlang.mk can manage Erlang itself
30.5. Erlang.mk can do more than Erlang
30.6. Erlang.mk integrates nicely in Make and Automake projects
31. Short history
31.1. Before Erlang.mk
31.2. Lifetime of the project
32. Contributing
32.1. Priorities
32.2. Bugs
32.3. Code
32.4. Packages
32.5. Documentation
32.6. Feature requests
   Next

 

 
 
diff --git a/guide/plugins_usage.html b/guide/plugins_usage.html
index 1d7159f..c6207e8 100644
--- a/guide/plugins_usage.html
+++ b/guide/plugins_usage.html
@@ -70,7 +70,7 @@ in one go if they wish to do so.
Plugins can include some help text by ext
     $(verbose) printf "%s\n" "" "Run benchmark: $(MAKE) perfs"

28.4. Early-stage plugins

Plugins declared in DEP_PLUGINS are loaded near the end of Erlang.mk. That’s why you have access to all previously initialized variables. However, if you want your plugin to add common dependencies to -your applications, a regular is loaded too late in the process. +your applications, a regular plugin is loaded too late in the process. You need to use "Early-stage plugins". They are declared using the DEP_EARLY_PLUGINS variable instead. Plugins listed in this variable are loaded near the beginning of Erlang.mk Otherwise, they work exactly @@ -81,7 +81,7 @@ BUILD_DEPS = common_deps DEP_EARLY_PLUGINS = common_deps

# In the plugin's early-plugins.mk
 DEPS += cowboy
 TEST_DEPS = ct_helper
-dep_ct_helper = git https://github.com/ninenines/ct_helper master

28.5. Loading plugins local to the application

If the Erlang.mk plugin lives in the same directory or repository as your +dep_ct_helper = git https://github.com/ninenines/ct_helper master

28.5. Loading plugins local to the application

If the Erlang.mk plugin lives in the same directory or repository as your application or library, then you can load it exactly like an external plugin: the dependency name is simply the name of your application or library.

For example, the following Makefile loads a plugin in the mk @@ -90,7 +90,21 @@ defaults to plugins.mk or # Loads ./early-plugins.mk DEP_EARLY_PLUGINS = $(PROJECT) # Loads ./plugins.mk -DEP_PLUGINS = $(PROJECT)

Prev Up Next
 Home 
+DEP_PLUGINS = $(PROJECT)

28.6. Adding templates via plugins

Plugins may add templates either from within their Makefile or from +an external file. The recommended method is to use an external file; +however do note it only works for Make 4 and above:

THIS := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+tpl_test_mk = $(file < $(THIS)/templates/my_template.erl)

With templates/my_template.erl containing:

-module(template_name).

Erlang.mk will do string substitution replacing the following +strings with their equivalent:

  • +template_name: the name provided by the user +
  • +project_name: either $(PROJECT) or the target application’s name +
  • +template_sp: internal; propagates whitespace settings to Makefiles +
  • +rel_deps_dir: internal; path to deps/* from within an apps/* Makefile +
  • +rel_root_dir: internal; path to top-level directory from within an apps/* Makefile +
Prev Up Next
 Home 
-- cgit v1.2.3