aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/beam_lib.xml
diff options
context:
space:
mode:
authorLars G Thorsen <[email protected]>2010-01-26 10:13:35 +0000
committerErlang/OTP <[email protected]>2010-01-26 18:55:11 +0100
commitdf88b47cdafcc2e04452456942ea572a7b72e2f2 (patch)
tree36da537a36b45ff406acb8e714dde97bbe31e7af /lib/stdlib/doc/src/beam_lib.xml
parent39ff2b44d130179d3ce722a9b3c07d27bfb72a2a (diff)
downloadotp-df88b47cdafcc2e04452456942ea572a7b72e2f2.tar.gz
otp-df88b47cdafcc2e04452456942ea572a7b72e2f2.tar.bz2
otp-df88b47cdafcc2e04452456942ea572a7b72e2f2.zip
OTP-8343 The documentation is now possible to build in an open source
environment after a number of bugs are fixed and some features are added in the documentation build process. - The arity calculation is updated. - The module prefix used in the function names for bif's are removed in the generated links so the links will look like http://www.erlang.org/doc/man/erlang.html#append_element-2 instead of http://www.erlang.org/doc/man/erlang.html#erlang:append_element-2 - Enhanced the menu positioning in the html documentation when a new page is loaded. - A number of corrections in the generation of man pages (thanks to Sergei Golovan) - Moved some man pages to more apropriate sections, pages in section 4 moved to 5 and pages in 6 moved to 7. - The legal notice is taken from the xml book file so OTP's build process can be used for non OTP applications.
Diffstat (limited to 'lib/stdlib/doc/src/beam_lib.xml')
-rw-r--r--lib/stdlib/doc/src/beam_lib.xml152
1 files changed, 79 insertions, 73 deletions
diff --git a/lib/stdlib/doc/src/beam_lib.xml b/lib/stdlib/doc/src/beam_lib.xml
index f2a9c2a671..b9286f1402 100644
--- a/lib/stdlib/doc/src/beam_lib.xml
+++ b/lib/stdlib/doc/src/beam_lib.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2000</year><year>2009</year>
+ <year>2000</year><year>2010</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -13,12 +13,12 @@
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
-
+
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
-
+
</legalnotice>
<title>beam_lib</title>
@@ -70,82 +70,88 @@
using <seealso marker="#strip/1">strip/1</seealso>,
<seealso marker="#strip_files/1">strip_files/1</seealso> and/or
<seealso marker="#strip_release/1">strip_release/1</seealso>.</p>
- <p><em>Reconstructing source code</em></p>
- <p>Here is an example of how to reconstruct source code from
- the debug information in a BEAM file <c>Beam</c>:</p>
- <code type="none">
+ <section>
+ <title>Reconstructing source code</title>
+ <p>Here is an example of how to reconstruct source code from
+ the debug information in a BEAM file <c>Beam</c>:</p>
+ <code type="none">
{ok,{_,[{abstract_code,{_,AC}}]}} = beam_lib:chunks(Beam,[abstract_code]).
io:fwrite("~s~n", [erl_prettypr:format(erl_syntax:form_list(AC))]).</code>
- <p><em>Encrypted debug information</em></p>
- <p>The debug information can be encrypted in order to keep
- the source code secret, but still being able to use tools such as
- Xref or Debugger. </p>
- <p>To use encrypted debug information, a key must be provided to
- the compiler and <c>beam_lib</c>. The key is given as a string and
- it is recommended that it contains at least 32 characters and
- that both upper and lower case letters as well as digits and
- special characters are used.</p>
- <p></p>
- <p>The default type -- and currently the only type -- of crypto
- algorithm is <c>des3_cbc</c>, three rounds of DES. The key string
- will be scrambled using <c>erlang:md5/1</c> to generate
- the actual keys used for <c>des3_cbc</c>.</p>
- <note>
- <p>As far as we know by the time of writing, it is
- infeasible to break <c>des3_cbc</c> encryption without any
- knowledge of the key. Therefore, as long as the key is kept
- safe and is unguessable, the encrypted debug information
- <em>should</em> be safe from intruders.</p>
- </note>
- <p>There are two ways to provide the key:</p>
- <list type="ordered">
- <item>
- <p>Use the compiler option <c>{debug_info,Key}</c>, see
- <seealso marker="compiler:compile#debug_info_key">compile(3)</seealso>,
- and the function
- <seealso marker="#crypto_key_fun/1">crypto_key_fun/1</seealso>
- to register a fun which returns the key whenever
- <c>beam_lib</c> needs to decrypt the debug information.</p>
- <p>If no such fun is registered, <c>beam_lib</c> will instead
- search for a <c>.erlang.crypt</c> file, see below.</p>
- </item>
- <item>
- <p>Store the key in a text file named <c>.erlang.crypt</c>.</p>
- <p>In this case, the compiler option <c>encrypt_debug_info</c>
- can be used, see
- <seealso marker="compiler:compile#encrypt_debug_info">compile(3)</seealso>.</p>
- </item>
- </list>
- <p><em>.erlang.crypt</em></p>
- <p><c>beam_lib</c> searches for <c>.erlang.crypt</c> in the current
- directory and then the home directory for the current user. If
- the file is found and contains a key, <c>beam_lib</c> will
- implicitly create a crypto key fun and register it.</p>
- <p>The <c>.erlang.crypt</c> file should contain a single list of
- tuples:</p>
- <code type="none">
+ </section>
+ <section>
+ <title>Encrypted debug information</title>
+ <p>The debug information can be encrypted in order to keep
+ the source code secret, but still being able to use tools such as
+ Xref or Debugger. </p>
+ <p>To use encrypted debug information, a key must be provided to
+ the compiler and <c>beam_lib</c>. The key is given as a string and
+ it is recommended that it contains at least 32 characters and
+ that both upper and lower case letters as well as digits and
+ special characters are used.</p>
+ <p></p>
+ <p>The default type -- and currently the only type -- of crypto
+ algorithm is <c>des3_cbc</c>, three rounds of DES. The key string
+ will be scrambled using <c>erlang:md5/1</c> to generate
+ the actual keys used for <c>des3_cbc</c>.</p>
+ <note>
+ <p>As far as we know by the time of writing, it is
+ infeasible to break <c>des3_cbc</c> encryption without any
+ knowledge of the key. Therefore, as long as the key is kept
+ safe and is unguessable, the encrypted debug information
+ <em>should</em> be safe from intruders.</p>
+ </note>
+ <p>There are two ways to provide the key:</p>
+ <list type="ordered">
+ <item>
+ <p>Use the compiler option <c>{debug_info,Key}</c>, see
+ <seealso marker="compiler:compile#debug_info_key">compile(3)</seealso>,
+ and the function
+ <seealso marker="#crypto_key_fun/1">crypto_key_fun/1</seealso>
+ to register a fun which returns the key whenever
+ <c>beam_lib</c> needs to decrypt the debug information.</p>
+ <p>If no such fun is registered, <c>beam_lib</c> will instead
+ search for a <c>.erlang.crypt</c> file, see below.</p>
+ </item>
+ <item>
+ <p>Store the key in a text file named <c>.erlang.crypt</c>.</p>
+ <p>In this case, the compiler option <c>encrypt_debug_info</c>
+ can be used, see
+ <seealso marker="compiler:compile#encrypt_debug_info">compile(3)</seealso>.</p>
+ </item>
+ </list>
+ </section>
+ <section>
+ <title>.erlang.crypt</title>
+ <p><c>beam_lib</c> searches for <c>.erlang.crypt</c> in the current
+ directory and then the home directory for the current user. If
+ the file is found and contains a key, <c>beam_lib</c> will
+ implicitly create a crypto key fun and register it.</p>
+ <p>The <c>.erlang.crypt</c> file should contain a single list of
+ tuples:</p>
+ <code type="none">
{debug_info, Mode, Module, Key}</code>
- <p><c>Mode</c> is the type of crypto algorithm; currently, the only
- allowed value thus is <c>des3_cbc</c>. <c>Module</c> is either an
- atom, in which case <c>Key</c> will only be used for the module
- <c>Module</c>, or <c>[]</c>, in which case <c>Key</c> will be
- used for all modules. <c>Key</c> is the non-empty key string.</p>
- <p>The <c>Key</c> in the first tuple where both <c>Mode</c> and
- <c>Module</c> matches will be used.</p>
- <p>Here is an example of an <c>.erlang.crypt</c> file that returns
- the same key for all modules:</p>
- <code type="none"><![CDATA[
+ <p><c>Mode</c> is the type of crypto algorithm; currently, the only
+ allowed value thus is <c>des3_cbc</c>. <c>Module</c> is either an
+ atom, in which case <c>Key</c> will only be used for the module
+ <c>Module</c>, or <c>[]</c>, in which case <c>Key</c> will be
+ used for all modules. <c>Key</c> is the non-empty key string.</p>
+ <p>The <c>Key</c> in the first tuple where both <c>Mode</c> and
+ <c>Module</c> matches will be used.</p>
+ <p>Here is an example of an <c>.erlang.crypt</c> file that returns
+ the same key for all modules:</p>
+ <code type="none"><![CDATA[
[{debug_info, des3_cbc, [], "%>7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].]]></code>
- <p>And here is a slightly more complicated example of an
- <c>.erlang.crypt</c> which provides one key for the module
- <c>t</c>, and another key for all other modules:</p>
- <code type="none"><![CDATA[
+ <p>And here is a slightly more complicated example of an
+ <c>.erlang.crypt</c> which provides one key for the module
+ <c>t</c>, and another key for all other modules:</p>
+ <code type="none"><![CDATA[
[{debug_info, des3_cbc, t, "My KEY"},
{debug_info, des3_cbc, [], "%>7}|pc/DM6Cga*68$Mw]L#&_Gejr]G^"}].]]></code>
- <note>
- <p>Do not use any of the keys in these examples. Use your own
- keys.</p>
- </note>
+ <note>
+ <p>Do not use any of the keys in these examples. Use your own
+ keys.</p>
+ </note>
+ </section>
</section>
<section>