From dfb899c0229f7ff7dbfad34d496e0429562728bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Valim?= Date: Wed, 8 Mar 2017 13:25:35 +0100 Subject: Store abstract code in the Dbgi chunk The new Dbgi chunk returns data in the following format: {debug_info_v1, Backend, Data} This allows compilers to store the debug info in different formats. In order to retrieve a particular format, for instance, Erlang Abstract Format, one may invoke: Backend:debug_info(erlang_v1, Module, Data, Opts) Besides introducing the chunk above, this commit also: * Changes beam_lib:chunk(Beam, [:abstract_code]) to read from the new Dbgi chunk while keeping backwards compatibility with old .beams * Adds the {debug_info, {Backend, Data}} option to compile:file/2 and friends that are stored in the Dbgi chunk. This allows the debug info encryption mechanism to work across compilers * Improves dialyzer to work directly on Core Erlang, allowing languages that do not have the Erlang Abstract Format to be dialyzer as long as they emit the new chunk and their backend implementation is available Backwards compatibility is kept across the board except for those calling beam_lib:chunk(Beam, ["Abst"]), as the old chunk is no longer available. Note however the "Abst" chunk has always been optional. Future OTP versions may remove parsing the "Abst" chunk altogether from beam_lib once Erlang 19 and earlier is no longer supported. The current Dialyzer implementation still supports earlier .beam files and such may also be removed in future versions. --- lib/stdlib/doc/src/beam_lib.xml | 46 ++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 12 deletions(-) (limited to 'lib/stdlib/doc') diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml index d5ec90b060..031d79d0e2 100644 --- a/lib/stdlib/doc/src/beam_lib.xml +++ b/lib/stdlib/doc/src/beam_lib.xml @@ -42,10 +42,10 @@ and the corresponding identifiers are as follows:

- abstract_code ("Abst") atoms ("Atom") attributes ("Attr") compile_info ("CInf") + debug_info ("Dbgi") exports ("ExpT") imports ("ImpT") indexed_imports ("ImpT") @@ -60,9 +60,8 @@ Debug Information/Abstract Code

Option debug_info can be specified to the Compiler (see compile(3)) - to have debug information in the form of abstract code (see section - The Abstract Format in the - ERTS User's Guide) stored in the abstract_code chunk. + to have debug information, such as Erlang + Abstract Format, stored in the debug_info chunk. Tools such as Debugger and Xref require the debug information to be included.

@@ -79,7 +78,7 @@
Reconstruct Source Code -

The following example shows how to reconstruct source code from +

The following example shows how to reconstruct Erlang source code from the debug information in a BEAM file Beam:

@@ -117,7 +116,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]). -

Use Compiler option {debug_info,Key}, see +

Use Compiler option {debug_info_key,Key}, see compile(3) and function crypto_key_fun/1 @@ -198,18 +197,40 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]). -

"Abst" | "Attr" | "CInf" | "ExpT" | "ImpT" | "LocT" | "Atom"

+

"Attr" | "CInf" | "Dbgi" | "ExpT" | "ImpT" | "LocT" | "AtU8"

+ + + +

The format stored in the debug_info chunk. + To retrieve particular code representation from the backend, + Backend:debug_info(Format, Module, Data, Opts) must be + invoked. Format is an atom, such as erlang_v1 for + the Erlang Abstract Format or core_v1 for Core Erlang. + Module is the module represented by the beam file and + Data is the value stored in the debug info chunk. + Opts is any list of values supported by the Backend. + Backend:debug_info/4 must return {ok, Code} or + {error, Term}.

+ +

Developers must always invoke the debug_info/4 function + and never rely on the Data stored in the debug_info + chunk, as it is opaque and may change at any moment. no_debug_info + means that chunk "Dbgi" is present, but empty.

+ +

It is not checked that the forms conform to the abstract format indicated by AbstVersion. no_abstract_code means that chunk "Abst" is present, but empty.

+

For modules compiled with OTP 20 onwards, the abst_code chunk + is automatically computed from the debug_info chunk.

 @@ -346,7 +367,7 @@ io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).

Registers an unary fun that is called if beam_lib must read an - abstract_code chunk that has been encrypted. The fun + debug_info chunk that has been encrypted. The fun is held in a process that is started by the function.

If a fun is already registered when attempting to register a fun, {error, exists} is returned.

@@ -443,7 +464,8 @@ CryptoKeyFun(clear) -> term()

Removes all chunks from a BEAM file except those needed by the loader. In particular, - the debug information (chunk abstract_code) is removed.

+ the debug information (chunk debug_info and abstract_code) + is removed.

 @@ -454,9 +476,9 @@ CryptoKeyFun(clear) -> term()

Removes all chunks except those needed by the loader from BEAM files. In particular, - the debug information (chunk abstract_code) is removed. - The returned list contains one element for each specified filename, - in the same order as in Files.

+ the debug information (chunk debug_info and abstract_code) + is removed. The returned list contains one element for each + specified filename, in the same order as in Files.

 -- cgit v1.2.3