From af8ba863113fe48b1e83f1a760775e03e3148c41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 31 May 2022 09:53:34 +0200 Subject: Update user guide --- guide/deps.html | 6 +++- guide/index.html | 2 +- guide/xref.html | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 94 insertions(+), 3 deletions(-) diff --git a/guide/deps.html b/guide/deps.html index fa9287c..f2de869 100644 --- a/guide/deps.html +++ b/guide/deps.html @@ -47,7 +47,11 @@ tools to find what you need, for example:

$ make
 to your project is a one-liner:
DEPS = cowboy
And that’s it! The next time you run make, Erlang.mk will
 fetch and compile Cowboy. Erlang.mk will also ensure Cowboy
 is available whenever you use the shell, run tests and any
-other operations.
Erlang.mk will fill in the application resource file with
+other operations.
Note though that you may need to specify the version of a
+dependency to use. Otherwise, you may get an outdated version,
+since the package index used by Erlang.mk is not always
+updated with the latest version of each package.
DEPS = cowboy
+dep_cowboy_commit = 2.8.0
Erlang.mk will fill in the application resource file with
 all applications found in DEPS. But not all dependencies
 are Erlang applications, and not all dependencies need to
 be a runtime dependency. That’s where the BUILD_DEPS
diff --git a/guide/index.html b/guide/index.html
index 415948f..4c7664d 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. Configuring paths
23.4. 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
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. Configuring paths
23.4. 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

 

 
 
diff --git a/guide/xref.html b/guide/xref.html
index 8c930a2..35ea94e 100644
--- a/guide/xref.html
+++ b/guide/xref.html
@@ -33,7 +33,94 @@ div.navfooter{margin-bottom:1em}
 
 

 
-
Prev   Next
Chapter 27. Xref
Placeholder chapter.
Prev Up Next
 Home 

+
Prev   Next
Chapter 27. Xref
Xref is a cross reference tool for analyzing dependencies
+between functions, modules, applications and releases.
+Erlang.mk provides an interface to analyzing all except
+the releases.
Both predefined checks and custom queries are supported
+in Erlang.mk.
27.1. Usage
To run Xref with the default predefined checks:
$ make xref
Erlang.mk will error out when warnings are found.
The following predefined checks can be used:
  • 
+undefined_function_calls
+
  • 
+undefined_functions (similar to the previous)
+
  • 
+locals_not_used (detected by the compiler)
+
  • 
+exports_not_used
+
  • 
+deprecated_function_calls (also detected by the compiler)
+
  • 
+deprecated_functions (similar to the previous)
+
  • 
+{deprecated_function_calls, Flag}
+
  • 
+{deprecated_functions, Flag} (similar to the previous)
+
Erlang.mk will only run the undefined_function_calls
+check by default.
To change the check the XREF_CHECKS variable can be used:
$ make xref XREF_CHECKS=exports_not_used
Multiple checks can be run at once. The checks variable
+must be defined as an Erlang list:
$ make xref XREF_CHECKS="[undefined_function_calls, exports_not_used]"
Erlang.mk also supports informational analyses. Those will
+not error out when results are found, since they are not
+errors. To find all modules that call cowboy_req functions:
$ make xref XREF_CHECKS="{module_use, cowboy_req}"
The following informational checks are supported:
  • 
+{call, MFA} - functions that MFA calls
+
  • 
+{use, MFA} - functions that call MFA
+
  • 
+{module_call, Mod} - modules that Mod calls (Mod depends on them)
+
  • 
+{module_use, Mod} - modules that call Mod (they depend on Mod)
+
  • 
+{application_call, App} - apps that App calls (App depends on them)
+
  • 
+{application_use, App} - apps that call App (they depend on App)
+
The scope might need to be increased in order to obtain
+the complete results of informational checks. This is
+especially true for module and applications, with
+application results being dependent on the applications
+being added to the scope to be found.
27.2. Queries
Erlang.mk provides an interface to the Xref query
+functions. To perform a query, the q variable
+must be used instead of XREF_CHECKS. For example,
+to obtain all unresolved calls:
$ make xref q=UC
The query language is documented at the top of the
+XRef manual page.
27.3. Analysis scope
Erlang.mk will set the scope of analysis to the current
+project by default. The scope can be automatically
+extended to the applications from multi-application
+repositories, to dependencies and to the built-in
+Erlang/OTP applications themselves.
To change the scope, the XREF_SCOPE variable can be
+set. The variable can either be set in your Makefile
+or from the command line. The following values can
+be defined:
  • 
+app - the current project
+
  • 
+apps - applications from multi-application repositories
+
  • 
+deps - dependencies
+
  • 
+otp - Erlang/OTP applications
+
To get the most complete analysis possible they should
+all be added to the variable:
$ make xref XREF_CHECKS="{application_use, ssl}" XREF_SCOPE="app apps deps otp"
+Application ssl is used by:
+- my_app
+- diameter
+- eldap
+- ftp
+- inets
+- ssl
Additional applications can be provided using the
+XREF_EXTRA_APP_DIRS variable. Note that these
+applications will need to be compiled before they
+can be found by Xref.
Similarly, non-application directories can be
+added using XREF_EXTRA_DIRS. The directory
+to be provided must be the one that contains
+the beam files.
27.4. Ignoring warnings
Sometimes it is necessary to ignore warnings because
+they are expected. This is the case for example
+when multiple Erlang/OTP versions must be supported
+and modules or functions have been added or removed.
Erlang.mk supports both project-wide configuration
+and Rebar-compatible inline ignores. To ignore
+warnings for a function in the current module the
+following line can be added to the source file:
-ignore_xref({log, 1}).
The module name can be specified explicitly:
-ignore_xref({my_mod, log, 1}).
As well as a full module can be ignored:
-ignore_xref(my_mod).
The ignored functions can be provided as a list:
-ignore_xref([{log, 1}, {pretty_print, 1}]).
The XREF_IGNORE variable can be used to define
+functions and modules to ignore project-wide. It
+accepts either MFAs or modules:
XREF_IGNORE={my_mod, log, 1}
Multiple ignores must be provided as an Erlang
+list:
XREF_IGNORE=[{my_mod, log, 1}, other_mod]
By default Erlang.mk will ignore unused exports
+for behavior callbacks when the exports_not_used
+check is run. It is possible to override this
+behavior, or to ignore the callbacks for queries
+and other checks, by defining the XREF_IGNORE_CALLBACKS
+variable:
$ make xref XREF_CHECKS=exports_not_used XREF_IGNORE_CALLBACKS=0
Prev Up Next
 Home 

 

 
 
-- 
cgit v1.2.3