diff options
Diffstat (limited to 'lib/reltool/doc')
22 files changed, 2201 insertions, 0 deletions
diff --git a/lib/reltool/doc/html/.gitignore b/lib/reltool/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/reltool/doc/html/.gitignore diff --git a/lib/reltool/doc/man3/.gitignore b/lib/reltool/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/reltool/doc/man3/.gitignore diff --git a/lib/reltool/doc/pdf/.gitignore b/lib/reltool/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/lib/reltool/doc/pdf/.gitignore diff --git a/lib/reltool/doc/src/Makefile b/lib/reltool/doc/src/Makefile new file mode 100644 index 0000000000..2c634bdf6c --- /dev/null +++ b/lib/reltool/doc/src/Makefile @@ -0,0 +1,105 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# 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. +# +# %CopyrightEnd% + +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(RELTOOL_VSN) +APPLICATION=reltool + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- + +include files.mk + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +XML_FILES = \ + $(BOOK_FILES) $(XML_CHAPTER_FILES) \ + $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_APPLICATION_FILES) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +man: $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + +release_spec: + diff --git a/lib/reltool/doc/src/book.gif b/lib/reltool/doc/src/book.gif Binary files differnew file mode 100644 index 0000000000..94b3868792 --- /dev/null +++ b/lib/reltool/doc/src/book.gif diff --git a/lib/reltool/doc/src/book.xml b/lib/reltool/doc/src/book.xml new file mode 100644 index 0000000000..f50d314711 --- /dev/null +++ b/lib/reltool/doc/src/book.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Reltool</title> + <prepared>Håkan Mattsson</prepared> + <docno></docno> + <date></date> + <rev>%VSN%/rev></rev> + </header> + <insidecover> + </insidecover> + <pagetext>Reltool</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> + <applications> + <xi:include href="ref_man.xml"/> + </applications> + <releasenotes> + <xi:include href="notes.xml"/> + </releasenotes> + <index></index> +</book> diff --git a/lib/reltool/doc/src/fascicules.xml b/lib/reltool/doc/src/fascicules.xml new file mode 100644 index 0000000000..a57808974e --- /dev/null +++ b/lib/reltool/doc/src/fascicules.xml @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="part" href="part_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> + Release Notes + </fascicule> + <fascicule file="" href="../../../../doc/print.html" entry="no"> + Off-Print + </fascicule> +</fascicules> diff --git a/lib/reltool/doc/src/files.mk b/lib/reltool/doc/src/files.mk new file mode 100644 index 0000000000..b2dc06411d --- /dev/null +++ b/lib/reltool/doc/src/files.mk @@ -0,0 +1,45 @@ +#-*-makefile-*- ; force emacs to enter makefile-mode +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# 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. +# +# %CopyrightEnd% + +XML_APPLICATION_FILES = \ + ref_man.xml + +XML_REF3_FILES = \ + reltool.xml + +XML_PART_FILES = \ + part.xml \ + part_notes.xml + +XML_CHAPTER_FILES = \ + reltool_intro.xml \ + reltool_usage.xml \ + reltool_examples.xml \ + notes.xml + +BOOK_FILES = book.xml + +GIF_FILES = \ + book.gif \ + note.gif \ + notes.gif \ + ref_man.gif \ + user_guide.gif \ + warning.gif + diff --git a/lib/reltool/doc/src/make.dep b/lib/reltool/doc/src/make.dep new file mode 100644 index 0000000000..59e77e8162 --- /dev/null +++ b/lib/reltool/doc/src/make.dep @@ -0,0 +1,20 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex part.tex ref_man.tex reltool.tex \ + reltool_examples.tex reltool_intro.tex reltool_usage.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + diff --git a/lib/reltool/doc/src/note.gif b/lib/reltool/doc/src/note.gif Binary files differnew file mode 100644 index 0000000000..6fffe30419 --- /dev/null +++ b/lib/reltool/doc/src/note.gif diff --git a/lib/reltool/doc/src/notes.gif b/lib/reltool/doc/src/notes.gif Binary files differnew file mode 100644 index 0000000000..e000cca26a --- /dev/null +++ b/lib/reltool/doc/src/notes.gif diff --git a/lib/reltool/doc/src/notes.xml b/lib/reltool/doc/src/notes.xml new file mode 100644 index 0000000000..293793e900 --- /dev/null +++ b/lib/reltool/doc/src/notes.xml @@ -0,0 +1,186 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Reltool Release Notes</title> + <prepared>Håkan Mattsson</prepared> + <docno></docno> + <date></date> + <rev></rev> + <file>notes.xml</file> + </header> + <p>This document describes the changes made to the Reltool system + from version to version. The intention of this document is to + list all incompatibilities as well as all enhancements and + bugfixes for every release of Reltool. Each release of Reltool + thus constitutes one section in this document. The title of each + section is the version number of Reltool.</p> + + + <section><title>Reltool 0.5.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the HTML frames are removed.</p> + <p> + Own Id: OTP-8254</p> + </item> + </list> + </section> + + </section> + + <section><title>Reltool 0.5.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + In the new release of Reltool (0.5) there is a severe bug + that may cause your source files to be deleted. The bug + is triggered when you generate a target system WITH + archive files AND your library directories are given with + absolute paths. (Library directories are given with the + ERL_LIBS environment variable or with the lib_dirs + configuration parameter.)</p> + <p> + Own Id: OTP-8199</p> + </item> + </list> + </section> + + </section> + + <section><title>Reltool 0.5</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The tool is still experimental. Feedback is appreciated. </p> + <p> + Major improvements of the target system generation has + been performed. Now it is possible to generate a + relocatable target system that does not need to be + re-installed if it is moved to a new location. Archive + files are automatically generated. A detailed + specification of the target system can be generated + without actually creating the target system. Relocatable + escripts are put in the bin directory of the target + system. etc. etc.</p> + <p> + Some new functions has been introduced in the + <c>reltool</c> module: <c>start/1, start_link/1, + get_config/3, get_target_spec/1 and + eval_target_spec/3</c>.</p> + <p> + Some new configuration parameters has been introduced: + <c>profile, incl_sys_filters, excl_sys_filters, + incl_app_filters, excl_app_filters, incl_archive_filters, + excl_archive_filters, archive_opts, escript and + relocatable</c>.</p> + <p> + Some parameters have been obsoleted and given new + semantics: <c>incl_erts_dirs (incl_sys_filters), + excl_erts_dirs (excl_sys_filters), incl_app_dirs + (incl_app_filters), excl_app_dirs (excl_app_filters) and + escripts (escript).</c></p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-7949</p> + </item> + </list> + </section> + + <section> + <title>Known Bugs and Problems</title> + <list> + <item> + <p> + The application is experimental. Feedback is appreciated.</p> + </item> + </list> + </section> + + </section> + + <section> + <title>Reltool 0.2.2</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The tool crashed when rel, script and boot files were + generated via the GUI. This has been fixed.</p> + <p> + Own Id: OTP-7999</p> + </item> + </list> + </section> + + </section> + + <section> + <title>Reltool 0.2.1</title> + + <section> + <title>Improvements and New Features</title> + + <list> + <item> + <p> + Minor GUI fixes</p> + <p> + Own Id: OTP-7840</p> + </item> + </list> + </section> + + </section> + + <section> + <title>Reltool 0.2</title> + <section> + <title>Improvements and new features</title> + <p>This is the first (experimental) release of Reltool.</p> + </section> + + <section> + <title>Known Bugs and Problems</title> + <list> + <item> + <p> + The application is experimental.</p> + </item> + </list> + </section> + </section> +</chapter> diff --git a/lib/reltool/doc/src/part.xml b/lib/reltool/doc/src/part.xml new file mode 100644 index 0000000000..f78022a718 --- /dev/null +++ b/lib/reltool/doc/src/part.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Reltool Users Guide</title> + <prepared>Håkan Mattsson</prepared> + <docno></docno> + <date></date> + <rev>%VSN%</rev> + </header> + <description> + <p><c>Reltool</c> is a release management tool. It analyses a given + Erlang/OTP installation and determines various dependencies + between applications. The <c>graphical</c> frontend depicts the + dependencies and enables interactive customization of a + target system. The backend provides a <c>batch</c> interface + for generation of customized target systems.</p> + </description> + <xi:include href="reltool_intro.xml"/> + <xi:include href="reltool_usage.xml"/> + <xi:include href="reltool_examples.xml"/> +</part> diff --git a/lib/reltool/doc/src/part_notes.xml b/lib/reltool/doc/src/part_notes.xml new file mode 100644 index 0000000000..5a2aeecce6 --- /dev/null +++ b/lib/reltool/doc/src/part_notes.xml @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Reltool Release Notes</title> + <prepared>Håkan Mattsson</prepared> + <docno></docno> + <date></date> + <rev>%VSN%</rev> + </header> + <description> + <p><c>Reltool</c> is a release management tool. It analyses a given + Erlang/OTP installation and determines various dependencies + between applications. The <c>graphical</c> frontend depicts the + dependencies and enables interactive customization of a + target system. The backend provides a <c>batch</c> interface + for generation of customized target systems.</p> + </description> + <xi:include href="notes.xml"/> +</part> diff --git a/lib/reltool/doc/src/ref_man.gif b/lib/reltool/doc/src/ref_man.gif Binary files differnew file mode 100644 index 0000000000..b13c4efd53 --- /dev/null +++ b/lib/reltool/doc/src/ref_man.gif diff --git a/lib/reltool/doc/src/ref_man.xml b/lib/reltool/doc/src/ref_man.xml new file mode 100644 index 0000000000..52602bd069 --- /dev/null +++ b/lib/reltool/doc/src/ref_man.xml @@ -0,0 +1,41 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Reltool Reference Manual</title> + <prepared>Håkan Mattsson</prepared> + <docno></docno> + <date></date> + <rev>%VSN%</rev> + </header> + <description> + <p><c>Reltool</c> is a release management tool. It analyses a given + Erlang/OTP installation and determines various dependencies + between applications. The <c>graphical</c> frontend depicts the + dependencies and enables interactive customization of a + target system. The backend provides a <c>batch</c> interface + for generation of customized target systems.</p> + </description> + <xi:include href="reltool.xml"/> +</application> diff --git a/lib/reltool/doc/src/reltool.xml b/lib/reltool/doc/src/reltool.xml new file mode 100644 index 0000000000..9786928ae8 --- /dev/null +++ b/lib/reltool/doc/src/reltool.xml @@ -0,0 +1,698 @@ +<?xml version="1.0" encoding="ISO-8859-1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>reltool</title> + <prepared>Håkan Mattsson</prepared> + <responsible>Håkan Mattsson</responsible> + <docno></docno> + <approved>Håkan Mattsson</approved> + <checked></checked> + <date></date> + <rev>%VSN%</rev> + </header> + <module>reltool</module> + <modulesummary>Main API of the Reltool application</modulesummary> + <description> + <p>This is an interface module for the Reltool application.</p> + + <p><em>Reltool</em> is a release management tool. It analyses a + given Erlang/OTP installation and determines various dependencies + between applications. The <c>graphical</c> frontend depicts the + dependencies and enables interactive customization of a target + system. The backend provides a <c>batch</c> interface for + generation of customized target systems.</p> + + <p>The tool uses an installed Erlang/OTP system as input. + <c>root_dir</c> is the root directory of the analysed system and + it defaults to the system executing <c>reltool</c>. Applications + may also be located outside <c>root_dir</c>. <c>lib_dirs</c> + defines additional library directories where applications + additional may reside and it defaults to the the directories + listed by the operating system environment variable + <c>ERL_LIBS</c>. See the module <c>code</c> for more info. + Finally single modules and entire applications may be read from + Escripts.</p> + + <p>Some configuration parameters control the behavior of Reltool + on system (<c>sys</c>) level. Others provide control on + application (<c>app</c>) level and yet others are on module + (<c>mod</c>) level. Module level parameters overrides application + level parameters and application level parameters overrides system + level parameters. Escript <c>escript</c> level parameters + overrides system level parameters.</p> + + <p>The following top level <c>options</c> are supported:</p> + + <taglist> + + <tag><c><![CDATA[config]]></c></tag> + <item> + <p>This is the main option and it controls the configuration + of <c>reltool</c>. It can either be a <c>sys</c> tuple or + a name of a <c>file</c> containing a sys tuple.</p> + </item> + + <tag><c><![CDATA[trap_exit]]></c></tag> + <item> + <p>This option controls the error handling behavior of + <c>reltool</c>. By default the window processes traps + exit, but this behavior can altered by setting + <c>trap_exit</c> to <c>false</c>.</p> + </item> + + <tag><c><![CDATA[wx_debug]]></c></tag> + <item> + <p>This option controls the debug level of <c>wx</c>. As its + name indicates it is only useful for debugging. See + <c>wx:debug/1</c> for more info.</p> + </item> + + </taglist> + + <p>Besides the already mentioned source parameters <c>root_dir</c> + and <c>lib_dirs</c>, the following system (<c>sys</c>) level + options are supported:</p> + + <taglist> + + <tag><c><![CDATA[erts]]></c></tag> + <item> + <p>Erts specific configuration. See application level options + below.</p> + </item> + + <tag><c><![CDATA[escript]]></c></tag> + <item> + <p>Escript specific configuration. An escript has a mandatory + file name and escript level options that are described + below.</p> + </item> + + <tag><c><![CDATA[app]]></c></tag> + <item> + <p>Application specific configuration. An application has a + mandatory name and application level options that are + described below.</p> + </item> + + <tag><c><![CDATA[mod_cond]]></c></tag> + <item> + <p>This parameter controls the module inclusion policy. It + defaults to <c>all</c> which means that if an application is + included (either explicitly or implicitly) all modules in that + application will be included. This implies that both modules + that exists on the <c>ebin</c> directory of the application, + as well as modules that are named in the <c>app</c> file will + be included. If the parameter is set to <c>ebin</c>, both + modules on the <c>ebin</c> directory and derived modules are + included. If the parameter is set to <c>app</c>, both modules + in the <c>app</c> file and derived modules are included. + <c>derived</c> means that only modules that are used by other + included modules are included. The <c>mod_cond</c> setting on + system level is used as default for all applications.</p> + </item> + + <tag><c><![CDATA[incl_cond]]></c></tag> + <item> + <p>This parameter controls the application and escript + inclusion policy. It defaults to <c>derived</c> which means + that the applications that not have any explicit + <c>incl_cond</c> setting, will only be included if any other + (explicitly or implicitly included) application uses it. The + value <c>include</c> implies that all applications and + escripts that that not have any explicit <c>incl_cond</c> + setting will be included. <c>exclude</c> implies that all + applications and escripts) that that not have any explicit + <c>incl_cond</c> setting will be excluded.</p> + </item> + + <tag><c><![CDATA[boot_rel]]></c></tag> + <item> + <p>A target system may have several releases but the one given + as <c>boot_rel</c> will be used as default when the system is + booting up.</p> + </item> + + <tag><c><![CDATA[rel]]></c></tag> + <item> + <p>Release specific configuration. Each release maps to a + <c>rel</c>, <c>script</c> and <c>boot </c> file. See the + module <c>systools</c> for more info about the details. Each + release has a name, a version and a set of applications with a + few release specific parameters such as type and included + applications.</p> + </item> + + <tag><c><![CDATA[relocatable]]></c></tag> + <item> + <p>This parameter controls whether the <c>erl</c> executable + in the target system automatically should determine where it + is installed or if it should use a hardcoded path to the + installation. In the latter case the target system must be + installed with <c>reltool:install/2</c> before it can be + used. If the system is relocatable, the file tree containing + the target system can be moved to another location without + re-installation. The default is <c>true</c>.</p> + </item> + + <tag><c><![CDATA[profile]]></c></tag> + <item> + <p>The creation of the specification for a target system is + performed in two steps. In the first step a complete + specification is generated. It will likely contain much more + files than you are interested in your customized target + system. In the second step the specification will be filtered + according to your filters. There you have the ability to + specify filters per application as well as system wide + filters. You can also select a <c>profile</c> for your + system. Depending on the <c>profile</c>, different default + filters will be used. There are three different profiles to + choose from: <c>development</c>, <c>embedded</c> and + <c>standalone</c>. <c>development</c> is default. The + parameters that are affected by the <c>profile</c> are: + <c>incl_sys_filters</c>, <c>excl_sys_filters</c>, + <c>incl_app_filters</c> and <c>excl_app_filters</c>.</p> + </item> + + <tag><c><![CDATA[app_file]]></c></tag> + <item> + <p>This parameter controls the default handling of the + <c>app</c> files when a target system is generated. It + defaults to <c>keep</c> which means that <c>app</c> files are + copied to the target system and their contents are kept as + they are. <c>strip</c> means that a new <c>app</c> file is + generated from the contents of the original <c>app</c> file + where the non included modules are removed from the + file. <c>all</c> does also imply that a new <c>app</c> file is + generated from the contents of the original <c>app</c> file, + with the difference that all included modules are added to the + file. If the application does not have any <c>app</c> file a + file will be created for <c>all</c> but not for <c>keep</c> + and <c>strip</c>.</p> + </item> + + <tag><c><![CDATA[debug_info]]></c></tag> + <item> + <p>The <c>debug_info</c> parameter controls whether the debug + information in the beam file should be kept (<c>keep</c>) or + stripped <c>strip</c> when the file is copied to the target + system.</p> + </item> + + <tag><c><![CDATA[incl_sys_filters]]></c></tag> + <item> + <p>This parameter normally contains a list of regular + expressions that controls which files in the system that + should be included. Each file in the target system must match + at least one of the listed regular expressions in order to be + included. Further the files may not match any filter in + <c>excl_sys_filters</c> in order to be included. Which + application files that should be included are controlled with + the parameters <c>incl_app_filters</c> and + <c>excl_app_filters</c>. This parameter defaults to + <c>[".*"]</c>.</p> + </item> + + <tag><c><![CDATA[excl_sys_filters]]></c></tag> + <item> + <p>This parameter normally contains a list of regular + expressions that controls which files in the system that not + should be included in the target system. In order to be + included, a file must match some filter in + <c>incl_sys_filters</c> but not any filter in + <c>excl_sys_filters</c>. This parameter defaults to + <c>[]</c>.</p> + </item> + <tag><c><![CDATA[incl_app_filters]]></c></tag> + <item> + <p>This parameter normally contains a list of regular + expressions that controls which application specific files + that should be included. Each file in the application must + match at least one of the listed regular expressions in order + to be included. Further the files may not match any filter in + <c>excl_app_filters</c> in order to be included. This + parameter defaults to <c>[".*"]</c>.</p> + </item> + + <tag><c><![CDATA[excl_app_filters]]></c></tag> + <item> + <p>This parameter normally contains a list of regular + expressions that controls which application specific files + that not should be included in the target system. In order to + be included, a file must match some filter in + <c>incl_app_filters</c> but not any filter in + <c>excl_app_filters</c>. This parameter defaults to + <c>[]</c>.</p> + </item> + + <tag><c><![CDATA[incl_archive_filters]]></c></tag> + <item> + <p>This parameter normally contains a list of regular + expressions that controls which top level directories in an + application that should be included in an archive file (as + opposed of beeing included as a regular directory outside the + archive). Each top directory in the application must match at + least one of the listed regular expressions in order to be + included. Further the files may not match any filter in + <c>excl_app_filters</c> in order to be included. This + parameter defaults to <c>[".*"]</c>.</p> + </item> + + <tag><c><![CDATA[excl_archive_filters]]></c></tag> + <item> + <p>This parameter normally contains a list of regular + expressions that controls which top level directories in an + application that not should be included in an archive file. In + order to be included in the application archive, a top + directory must match some filter in <c>incl_archive_filters</c> + but not any filter in <c>excl_archive_filters</c>. This + parameter defaults to <c>["^include$","^priv$"]</c>.</p> + </item> + + <tag><c><![CDATA[archive_opts]]></c></tag> + <item> + <p>This parameter contains a list of options that are given to + <c>zip:create/3</c> when application specific files are + packaged into an archive. All options are not supported. The + most useful options in this context, are the ones that + controls which types of files that should be compressed. This + parameter defaults to <c>[]</c>.</p> + </item> + + </taglist> + + <p>On application (<c>escript</c>) level,the following options are + supported:</p> + + <taglist> + <tag><c><![CDATA[incl_cond]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + </taglist> + + <p>On application (<c>app</c>) level,the following options are + supported:</p> + + <taglist> + <tag><c><![CDATA[vsn]]></c></tag> + <item> + <p>The version of the application. In an installed system there may + exist several versions of an application. The <c>vsn</c> parameter + controls which version of the application that will be choosen. If it + is omitted, the latest version will be choosen.</p> + </item> + <tag><c><![CDATA[mod]]></c></tag> + <item> + <p>Module specific configuration. A module has a mandatory + name and module level options that are described below.</p> + </item> + <tag><c><![CDATA[mod_cond]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + <tag><c><![CDATA[incl_cond]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + <tag><c><![CDATA[app_file]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + <tag><c><![CDATA[debug_info]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + <tag><c><![CDATA[incl_app_filters]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + <tag><c><![CDATA[excl_app_filters]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + + <tag><c><![CDATA[incl_archive_filters]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + + <tag><c><![CDATA[excl_archive_filters]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + + <tag><c><![CDATA[archive_opts]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with the + same name on system level.</p> + </item> + </taglist> + + <p>On module (<c>mod</c>) level,the following options are + supported:</p> + + <taglist> + <tag><c><![CDATA[incl_cond]]></c></tag> + <item> + <p>This parameter controls whether the module is included or not. By + default the <c>mod_incl</c> parameter on application and system level + will be used to control whether the module is included or not. The + value of <c>incl_cond</c> overrides the module inclusion policy. + <c>include</c> implies that the module is included, while + <c>exclude</c> implies that the module not is included. + <c>derived</c> implies that the is included if any included uses the + module.</p> + </item> + <tag><c><![CDATA[debug_info]]></c></tag> + <item> + <p>The value of this parameter overrides the parameter with + the same name on application level.</p> + </item> + </taglist> + + </description> + + <section> + <title>DATA TYPES</title> + <code type="none"><![CDATA[ +options() = [option()] +option() = {config, config() | file()} + | {trap_exit, bool()} + | {wx_debug, term()} +config() = {sys, [sys()]} +sys() = {root_dir, root_dir()} + | {lib_dirs, [lib_dir()]} + | {profile, profile()} + | {erts, app()} + | {escript, escript_file(), [escript()]} + | {app, app_name(), [app()]} + | {mod_cond, mod_cond()} + | {incl_cond, incl_cond()} + | {boot_rel, boot_rel()} + | {rel, rel_name(), rel_vsn(), [rel_app()]} + | {relocatable, relocatable()} + | {app_file, app_file()} + | {debug_info, debug_info()} + | {incl_sys_filters, incl_sys_filters()} + | {excl_sys_filters, excl_sys_filters()} + | {incl_app_filters, incl_app_filters()} + | {excl_app_filters, excl_app_filters()} + | {incl_archive_filters, incl_archive_filters()} + | {excl_archive_filters, excl_archive_filters()} + | {archive_opts, [archive_opt()]} +app() = {vsn, app_vsn()} + | {mod, mod_name(), mod()} + | {mod_cond, mod_cond()} + | {incl_cond, incl_cond()} + | {debug_info, debug_info()} + | {app_file, app_file()} + | {incl_sys_filters, incl_sys_filters()} + | {excl_sys_filters, excl_sys_filters()} + | {incl_app_filters, incl_app_filters()} + | {excl_app_filters, excl_app_filters()} + | {incl_archive_filters, incl_archive_filters()} + | {excl_archive_filters, excl_archive_filters()} + | {archive_opts, [archive_opt()]} +mod() = {vsn, app_vsn()} + | {incl_cond, incl_cond()} + | {debug_info, debug_info()} +rel_app() = app_name() + | {app_name(), app_type()} + | {app_name(), [incl_app()]} + | {app_name(), app_type(), [incl_app()]} +app_name() = atom() +app_type() = permanent | transient | temporary | load | none +app_vsn() = string() +archive_opt = zip_create_opt() +boot_rel() = rel_name() +app_file() = keep | strip | all +debug_info() = keep | strip +dir() = string() +escript() = {incl_cond, incl_cond()} +escript_file() = file() +excl_app_filters() = regexps() +excl_archive_filters() = regexps() +excl_sys_filters() = regexps() +file() = string() +incl_app() = app_name() +incl_app_filters() = regexps() +incl_archive_filters() = regexps() +incl_cond() = include | exclude | derived +incl_sys_filters() = regexps() +lib_dir() = dir() +mod_cond() = all | app | ebin | derived | none +mod_name() = atom() +profile() = development | embedded | standalone +re_regexp() = string() +reason() = string() +regexps() = [re_regexp()] | {add, [re_regexp()]} | {del, [re_regexp()]} +rel_file() = term() +rel_name() = string() +rel_vsn() = string() +relocatable = boolean() +root_dir() = dir() +script_file() = term() +server() = server_pid() | options() +server_pid() = pid() +target_dir() = file() +window_pid() = pid()]]></code> + + <marker id="start"></marker> + </section> + + <funcs> + <func> + <name>create_target(Server, TargetDir) -> ok | {error, Reason}</name> + <fsummary>Create a target system</fsummary> + <type> + <v>Server = server()</v> + <v>TargetDir = target_dir()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Create a target system. Gives the same result as + <c>{ok,TargetSpec}=reltool:get_target_spec(Server)</c> and + <c>reltool:eval_target_spec(TargetSpec,RootDir,TargetDir)</c>.</p></desc> + </func> + + <func> + <name>eval_target_spec(TargetSpec, RootDir, TargetDir) -> ok | {error, Reason}</name> + <fsummary>Create a target system</fsummary> + <type> + <v>TargetSpec = target_spec()</v> + <v>RootDir = root_dir()</v> + <v>TargetDir = target_dir()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Create the actual target system from a specification + generated by <c>reltool:get_target_spec/1</c>. The creation of + the specification for a target system is performed in two + steps. In the first step a complete specification will be + generated. It will likely contain much more files than you are + interested in in your target system. In the second step the + specification will be filtered according to your filters. There + you have the ability to specify filters per application as well + as system wide filters. You can also select a <c>profile</c> for + your system. Depending on the <c>profile</c>, different default + filters will be used.</p> + + <p>The top directories <c>bin</c>, <c>releases</c> and + <c>lib</c> are treated differently from other files. All other + files are by default copied to the target system. The + <c>releases</c> directory contains generated <c>rel</c>, + <c>script</c>, and <c>boot</c> files. The <c>lib</c> directory + contains the applications. Which applications that are included + and if they should be customized (archived, stripped from debug + info etc.) is specified with various configuration + parameters. The files in the <c>bin</c> directory are copied + from the <c>erts-vsn/bin</c> directory, but only those files + that was originally included in <c>bin</c> directory of the + source system.</p> + + <p>If the configuration parameter <c>relocatable</c> was set to + <c>true</c> there is no need to install the target system with + <c>reltool:install/2</c> before it can be started. In that case + the file tree containing the target system can be moved without + re-installation.</p></desc> + </func> + + <func> + <name>get_config(Server) -> {ok, Config} | {error, Reason}</name> + <fsummary>Get reltool configuration</fsummary> + <type> + <v>Server = server()</v> + <v>Config = config()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Get reltool configuration. Shorthand for + <c>reltool:get_config(Server,false,false)</c>.</p></desc> + </func> + + <func> + <name>get_config(Server, InclDefaults, InclDerived) -> {ok, Config} | {error, Reason}</name> + <fsummary>Get reltool configuration</fsummary> + <type> + <v>Server = server()</v> + <v>InclDefaults = incl_defaults()</v> + <v>InclDerived = incl_derived()</v> + <v>Config = config()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Get reltool configuration. Normally, only the explicit + configuration parameters with values that differs from their + defaults are interesting. But the builtin default values can be + returned by setting <c>InclDefaults</c> to <c>true</c>. The + derived configuration can be return by setting + <c>InclDerived</c> to <c>true</c>.</p></desc> + </func> + + <func> + <name>get_rel(Server, Relname) -> {ok, RelFile} | {error, Reason}</name> + <fsummary>Get contents of a release file</fsummary> + <type> + <v>Server = server()</v> + <v>RelName = rel_name()</v> + <v>RelFile = rel_file()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Get contents of a release file. See <c>rel(4)</c> for more + details.</p></desc> + </func> + + <func> + <name>get_script(Server, Relname) -> {ok, ScriptFile | {error, Reason}</name> + <fsummary>Get contents of a boot script file</fsummary> + <type> + <v>Server = server()</v> + <v>RelName = rel_name()</v> + <v>ScriptFile = script_file()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Get contents of a boot script file. See <c>script(4)</c> for + more details.</p></desc> + </func> + + <func> + <name>get_server(WindowPid) -> {ok, ServerPid} | {error, Reason}</name> + <fsummary>Start server process with options</fsummary> + <type> + <v>WindowPid = window_pid()</v> + <v>ServerPid = server_pid()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Return the process identifier of the server process.</p></desc> + </func> + + <func> + <name>get_target_spec(Server) -> {ok, targetSpec} | {error, Reason}</name> + <fsummary>Return a specification of the target system</fsummary> + <type> + <v>Server = server()</v> + <v>TargetSpec = target_spec()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Return a specification of the target system. The actual + target system can be created with + <c>reltool:eval_target_spec/3</c>.</p> + </desc> + </func> + + <func> + <name>install(Server, TargetDir) -> ok | {error, Reason}</name> + <fsummary>Install a target system</fsummary> + <type> + <v>Server = server()</v> + <v>TargetDir = target_dir()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Install a created target system</p></desc> + </func> + + <func> + <name>start() -> {ok, WindowPid} | {error, Reason}</name> + <fsummary>Start main window process</fsummary> + <type> + <v>WindowPid = window_pid()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Start a main window process with default options</p></desc> + </func> + + <func> + <name>start(Options) -> {ok, WindowPid} | {error, Reason}</name> + <fsummary>Start main window process with options</fsummary> + <type> + <v>Options = options()</v> + <v>WindowPid = window_pid()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Start a main window process with options</p></desc> + </func> + + <func> + <name>start_link(Options) -> {ok, WindowPid} | {error, Reason}</name> + <fsummary>Start main window process with options</fsummary> + <type> + <v>Options = options()</v> + <v>WindowPid = window_pid()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Start a main window process with options. The process is linked.</p></desc> + </func> + + <func> + <name>start_server(Options) -> {ok, ServerPid} | {error, Reason}</name> + <fsummary>Start server process with options</fsummary> + <type> + <v>Options = options()</v> + <v>ServerPid = server_pid()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Start a server process with options. The server process + identity can be given as argument to several other functions in the + API.</p></desc> + </func> + + <func> + <name>stop(Pid) -> ok | {error, Reason}</name> + <fsummary>Stop a server or window process</fsummary> + <type> + <v>Pid = server_pid() | window_pid()()</v> + <v>Reason = reason()</v> + </type> + <desc><p>Stop a server or window process</p></desc> + </func> + </funcs> + +</erlref> diff --git a/lib/reltool/doc/src/reltool_examples.xml b/lib/reltool/doc/src/reltool_examples.xml new file mode 100644 index 0000000000..3d087862e6 --- /dev/null +++ b/lib/reltool/doc/src/reltool_examples.xml @@ -0,0 +1,466 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may noot use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Examples</title> + <prepared>Håkan Mattsson</prepared> + <responsible>Håkan Mattsson</responsible> + <docno></docno> + <approved>Håkan Mattsson</approved> + <checked></checked> + <date></date> + <rev>%VSN%</rev> + <file>reltool_examples.xml</file> + </header> + + <section> + <title>Start and stop windows and servers</title> + + <p>The main process in Reltool is the server. It can be used as it + is or be used via the GUI frontend process. When the GUI is + started, a server process will automatically be started. The GUI + process is started with <c>reltool:start/0</c>, + <c>reltool:start/1</c> or <c>reltool:start_link/1</c>. The pid of + its server can be obtained with <c>reltool:get_server/1</c></p> + + <pre> +Erlang R13B02 (erts-5.7.3) [source] [64-bit] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false] + +Eshell V5.7.3 (abort with ^G) +1> {ok, Win} = reltool:start([]). +{ok,<0.36.01>} +2> {ok, Server} = reltool:get_server([]). +{ok,<0.37.01>} +3> reltool:get_config(Server). +{ok,{sys,[]}} +4> reltool:stop(Win). +ok + + +5> {ok, Server2} = reltool:start_server([]). +{ok,<0.6535.01>} +6> reltool:get_config(Server2). +{ok,{sys,[]}} +7> reltool:stop(Server2). +ok + </pre> + + </section> + + <section> + <title>Inspecting the configuration</title> + + <pre> +Erlang R13B02 (erts-5.7.3) [source] [64-bit] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false] + +Eshell V5.7.3 (abort with ^G) +1> Config = {sys, [{escript, "examples/display_args", [{incl_cond, include}]}, + {app, inets, [{incl_cond, include}]}, + {app, mnesia, [{incl_cond, exclude}]}, + {app, ssl, [{incl_cond, exclude}]}, + {app, runtime_tools, [{incl_cond, exclude}]}, + {app, syntax_tools, [{incl_cond, exclude}]}]}. +{sys,[{escript,"examples/display_args",[{incl_cond,include}]}, + {app,inets,[{incl_cond,include}]}, + {app,mnesia,[{incl_cond,exclude}]}, + {app,ssl,[{incl_cond,exclude}]}, + {app,runtime_tools,[{incl_cond,exclude}]}, + {app,syntax_tools,[{incl_cond,exclude}]}]} + + + +2> {ok, Server} = reltool:start_server([Config]). +{ok,<0.35.0>} +3> reltool:get_config(Server). +{ok,{sys,[{escript,"/clearcase/otp/tools/reltool/examples/display_args", + [{incl_cond,include}]}]}} +4> reltool:get_config(Server, false, false). +{ok,{sys,[{escript,"/clearcase/otp/tools/reltool/examples/display_args", + [{incl_cond,include}]}]}} + + + +5> reltool:get_config(Server, true, false). +{ok,{sys,[{root_dir,"/ldisk/hakan/otp_test"}, + {lib_dirs,[]}, + {escript,"/clearcase/otp/tools/reltool/examples/display_args", + [{incl_cond,include}]}, + {mod_cond,all}, + {incl_cond,derived}, + {boot_rel,"start_clean"}, + {emu_name,"beam"}, + {relocatable,true}, + {profile,development}, + {incl_sys_files,[".*"]}, + {excl_sys_files,[]}, + {incl_app_files,[".*"]}, + {excl_app_files,[]}, + {incl_archive_dirs,[".*"]}, + {excl_archive_dirs,["^include$","^priv$"]}, + {archive_opts,[]}, + {app_type,permanent}, + {app_file,keep}, + {debug_info,keep}]}} + + + +6> reltool:get_config(Server, true, true). +{ok,{sys,[{root_dir,"/ldisk/hakan/otp_test"}, + {lib_dirs,[]}, + {escript,"/clearcase/otp/tools/reltool/examples/display_args", + [{incl_cond,include}]}, + {mod_cond,all}, + {incl_cond,derived}, + {erts,[{vsn,"5.7.3"}, + {mod,erl_prim_loader,[]}, + {mod,erlang,[]}, + {mod,init,[]}, + {mod,otp_ring0,[]}, + {mod,prim_file,[]}, + {mod,prim_inet,[]}, + {mod,prim_zip,[]}, + {mod,zlib,[]}]}, + {app,compiler, + [{vsn,"4.6.3"}, + {mod,beam_asm,[]}, + {mod,beam_block,[]}, + {mod,beam_bool,[]}, + {mod,beam_bsm,[]}, + {mod,beam_clean,[]}, + {mod,beam_dead,[]}, + {mod,beam_dict,[]}, + {mod,beam_disasm,[]}, + {mod,beam_flatten,[]}, + {mod,beam_jump,[]}, + {mod,beam_listing,[]}, + {mod,beam_opcodes,...}, + {mod,...}, + {...}|...]}, + {app,crypto, + [{vsn,"1.6.1"}, + {mod,crypto,[]}, + {mod,crypto_app,[]}, + {mod,crypto_server,[]}, + {mod,crypto_sup,[]}]}, + {app,hipe, + [{vsn,"3.7.3"}, + {mod,cerl_cconv,[]}, + {mod,cerl_closurean,[]}, + {mod,cerl_hipeify,[]}, + {mod,cerl_hybrid_transform,[]}, + {mod,cerl_lib,[]}, + {mod,cerl_messagean,[]}, + {mod,cerl_pmatch,[]}, + {mod,cerl_prettypr,[]}, + {mod,cerl_to_icode,[]}, + {mod,cerl_typean,...}, + {mod,...}, + {...}|...]}, + {app,kernel, + [{vsn,"2.13.3"}, + {mod,application,[]}, + {mod,application_controller,[]}, + {mod,application_master,[]}, + {mod,application_starter,[]}, + {mod,auth,[]}, + {mod,code,[]}, + {mod,code_server,[]}, + {mod,disk_log,[]}, + {mod,disk_log_1,...}, + {mod,...}, + {...}|...]}, + {app,stdlib, + [{vsn,"1.16.3"}, + {mod,array,[]}, + {mod,base64,[]}, + {mod,beam_lib,[]}, + {mod,c,[]}, + {mod,calendar,[]}, + {mod,dets,[]}, + {mod,dets_server,[]}, + {mod,dets_sup,...}, + {mod,...}, + {...}|...]}, + {boot_rel,"start_clean"}, + {emu_name,"beam"}, + {relocatable,true}, + {profile,development}, + {incl_sys_files,[".*"]}, + {excl_sys_files,[]}, + {incl_app_files,[".*"]}, + {excl_app_files,[]}, + {incl_archive_dirs,[".*"]}, + {excl_archive_dirs,["^include$",[...]]}, + {archive_opts,[]}, + {app_type,permanent}, + {app_file,...}, + {...}]}} + + + +7> reltool:get_config([{sys,[{profile, embedded}]}]). +{ok,{sys,[{profile,embedded}, + {incl_sys_filters,["^bin","^erts","^lib","^releases"]}, + {excl_sys_filters,["^bin/(erlc|dialyzer|typer)(|\\.exe)$", + "^erts.*/bin/(erlc|dialyzer|typer)(|\\.exe)$", + "^erts.*/bin/.*(debug|pdb)"]}, + {incl_app_filters,["^ebin","^include","^priv"]}]}} +8> reltool:get_config([{sys,[{profile, standalone}]}]). +{ok,{sys,[{profile,standalone}, + {incl_sys_filters,["^bin/(erl|epmd)(|\\.exe|\\.ini)$", + "^bin/start(|_clean).boot$","^erts.*/bin","^lib$"]}, + {excl_sys_filters,["^erts.*/bin/(erlc|dialyzer|typer)(|\\.exe)$", + "^erts.*/bin/(start|escript|to_erl|run_erl)(|\\.exe)$", + "^erts.*/bin/.*(debug|pdb)"]}, + {incl_app_filters,["^ebin","^priv"]}, + {excl_app_filters,["^ebin/.*\\.appup$"]}]}} + + </pre> + + </section> + + <section> + <title>Generate release and script files</title> + <pre> +5> {ok, Server} = reltool:start_server([{config, {sys, [{boot_rel, "NAME"}, + {rel, "NAME", "VSN", [kernel, stdlib, sasl]}]}}]). +{ok,<0.1288.0>} +6> reltool:get_config(Server). +{ok,{sys,[{boot_rel,"NAME"}, + {rel,"NAME","VSN",[kernel,stdlib,sasl]}]}} +7> reltool:get_rel(Server, "NAME"). +{ok,{release,{"NAME","VSN"}, + {erts,"5.7"}, + [{kernel,"2.13"},{stdlib,"1.16"},{sasl,"2.1.6"}]}} +8> reltool:get_script(Server, "NAME"). +{ok,{script,{"NAME","VSN"}, + [{preLoaded,[erl_prim_loader,erlang,init,otp_ring0, + prim_file,prim_inet,prim_zip,zlib]}, + {progress,preloaded}, + {path,["$ROOT/lib/kernel-2.13/ebin", + "$ROOT/lib/stdlib-1.16/ebin"]}, + {primLoad,[error_handler]}, + {kernel_load_completed}, + {progress,kernel_load_completed}, + {path,["$ROOT/lib/kernel-2.13/ebin"]}, + {primLoad,[application,application_controller, + application_master,application_starter,auth,code, + code_server,disk_log,disk_log_1,disk_log_server, + disk_log_sup,dist_ac,dist_util,erl_boot_server|...]}, + {path,["$ROOT/lib/stdlib-1.16/ebin"]}, + {primLoad,[array,base64,beam_lib,c,calendar,dets, + dets_server,dets_sup,dets_utils,dets_v8,dets_v9,dict|...]}, + {path,["$ROOT/lib/sasl-2.1.6/ebin"]}, + {primLoad,[alarm_handler,erlsrv,format_lib_supp,misc_supp, + overload,rb,rb_format_supp,release_handler, + release_handler_1,sasl|...]}, + {progress,modules_loaded}, + {path,["$ROOT/lib/kernel-2.13/ebin", + "$ROOT/lib/stdlib-1.16/ebin","$ROOT/lib/sasl-2.1.6/ebin"]}, + {kernelProcess,heart,{heart,start,[]}}, + {kernelProcess,error_logger,{error_logger,start_link,[]}}, + {kernelProcess,application_controller, + {application_controller,start,[{...}]}}, + {progress,init_kernel_started}, + {apply,{application,load,[...]}}, + {apply,{application,load,...}}, + {progress,applications_loaded}, + {apply,{...}}, + {apply,...}, + {...}|...]}} +9> reltool:stop(Server). +ok + </pre> + </section> + + <section> + <title>Create a target system</title> + <pre> +Erlang R13B02 (erts-5.7.3) [source] [64-bit] [smp:4:4] [rq:4] [async-threads:0] [kernel-poll:false] + +Eshell V5.7.3 (abort with ^G) +1> Config = {sys, [{escript, "examples/display_args", [{incl_cond, include}]}, + {app, inets, [{incl_cond, include}]}, + {app, mnesia, [{incl_cond, exclude}]}, + {app, ssl, [{incl_cond, exclude}]}, + {app, runtime_tools, [{incl_cond, exclude}]}, + {app, syntax_tools, [{incl_cond, exclude}]}]}. +{sys,[{escript,"examples/display_args",[{incl_cond,include}]}, + {app,inets,[{incl_cond,include}]}, + {app,mnesia,[{incl_cond,exclude}]}, + {app,ssl,[{incl_cond,exclude}]}, + {app,runtime_tools,[{incl_cond,exclude}]}, + {app,syntax_tools,[{incl_cond,exclude}]}]} + + + +2> {ok, Spec} = reltool:get_target_spec([Config]). +{ok,[{create_dir,"releases", + [{write_file,"start_erl.data","5.7.3 1.0"}, + {create_dir,"1.0", + [{write_file,"start_clean.rel", + [37,37,32,114,101,108,32,103,101,110,101,114,97,116|...]}, + {write_file,"start_clean.script", + [37,37,32,115,99,114,105,112,116,32,103,101,110|...]}, + {write_file,"start_clean.boot", + <<131,104,3,100,0,6,115,99,114,105,112,116,...>>}, + {write_file,"start_sasl.rel", + [37,37,32,114,101,108,32,103,101,110,101|...]}, + {write_file,"start_sasl.script", + [37,37,32,115,99,114,105,112,116,32|...]}, + {write_file,"start_sasl.boot", + <<131,104,3,100,0,6,115,99,114,...>>}]}]}, + {create_dir,"bin", + [{copy_file,"display_args.escript", + "/clearcase/otp/tools/reltool/examples/display_args"}, + {copy_file,"display_args","erts-5.7.3/bin/escript"}, + {copy_file,"start","erts-5.7.3/bin/start"}, + {copy_file,"erl","erts-5.7.3/bin/dyn_erl"}, + {copy_file,"epmd","erts-5.7.3/bin/epmd"}, + {copy_file,"to_erl","erts-5.7.3/bin/to_erl"}, + {copy_file,"run_erl","erts-5.7.3/bin/run_erl"}, + {copy_file,"escript","erts-5.7.3/bin/escript"}, + {copy_file,"erlc","erts-5.7.3/bin/erlc"}, + {copy_file,"dialyzer","erts-5.7.3/bin/dialyzer"}, + {copy_file,"typer","erts-5.7.3/bin/typer"}, + {write_file,"start_clean.boot", + <<131,104,3,100,0,6,115,...>>}, + {write_file,"start_sasl.boot",<<131,104,3,100,0,6,...>>}, + {write_file,"start.boot",<<131,104,3,100,0,...>>}]}, + {create_dir,"misc", + [{copy_file,"makewhatis"},{copy_file,"format_man_pages"}]}, + {copy_file,"Install"}, + {create_dir,"usr", + [{create_dir,"lib", + [{copy_file,"liberts_r.a"},{copy_file,"liberts.a"}]}, + {create_dir,"include", + [{copy_file,"erl_fixed_size_int_types.h"}, + {copy_file,"erl_int_sizes_config.h"}, + {copy_file,"erl_memory_trace_parser.h"}, + {create_dir,"obsolete",[{copy_file,"driver.h"}]}, + {copy_file,"driver_int.h"}, + {copy_file,"erl_driver.h"}]}]}, + {create_dir,"erts-5.7.3", + [{create_dir,"lib", + [{create_dir,"internal", + [{copy_file,"liberts_internal_r.a"}, + {copy_file,"liberts_internal.a"}, + {copy_file,"libethread.a"}, + {copy_file,"README"}]}, + {copy_file,"liberts_r.a"}, + {copy_file,"liberts.a"}]}, + {create_dir,"bin", + [{copy_file,"start"}, + {copy_file,"erl","erts-5.7.3/bin/dyn_erl"}, + {copy_file,"epmd"}, + {copy_file,"to_erl"}, + {copy_file,"run_erl"}, + {copy_file,"escript"}, + {copy_file,"erlc"}, + {copy_file,"dialyzer"}, + {copy_file,"typer"}, + {copy_file,"erlexec"}, + {copy_file,[...]}, + {copy_file,...}, + {...}|...]}, + {create_dir,"doc",[]}, + {create_dir,"man",[]}, + {create_dir,"include", + [{create_dir,"internal", + [{create_dir,"tile",[{copy_file,...},{...}]}, + {create_dir,"sparc64",[{...}]}, + {create_dir,"sparc32",[...]}, + {create_dir,[...],...}, + {create_dir,...}, + {...}|...]}, + {copy_file,"erl_fixed_size_int_types.h"}, + {copy_file,"erl_int_sizes_config.h"}, + {copy_file,"erl_memory_trace_parser.h"}, + {copy_file,"driver_int.h"}, + {copy_file,"erl_driver.h"}]}, + {create_dir,"src",[{copy_file,"setuid_socket_wrap.c"}]}]}, + {create_dir,"lib", + [{archive,"compiler-4.6.3.ez",[], + [{create_dir,"compiler-4.6.3", + [{create_dir,"ebin", + [{copy_file,"compiler.appup"}, + {copy_file,[...]}, + {copy_file,...}, + {...}|...]}, + {create_dir,"src", + [{copy_file,[...]},{copy_file,...},{...}|...]}]}]}, + {archive,"crypto-1.6.1.ez",[], + [{create_dir,"crypto-1.6.1", + [{create_dir,"ebin", + [{copy_file,[...]},{copy_file,...},{...}|...]}, + {create_dir,"src",[{copy_file,...},{...}|...]}]}]}, + {create_dir,"crypto-1.6.1", + [{create_dir,"priv", + [{create_dir,"lib",[{copy_file,[...]}]}, + {create_dir,"obj",[{copy_file,...},{...}]}]}]}, + {archive,"erts-5.7.3.ez",[], + [{create_dir,"erts-5.7.3", + [{create_dir,"ebin",[{...}|...]}, + {create_dir,"src",[...]}]}]}, + {archive,"hipe-3.7.3.ez",[], + [{create_dir,"hipe-3.7.3", + [{create_dir,"util",[...]}, + {create_dir,[...],...}, + {create_dir,...}, + {...}|...]}]}, + {archive,"kernel-2.13.3.ez",[], + [{create_dir,"kernel-2.13.3", + [{create_dir,[...],...},{create_dir,...},{...}]}]}, + {create_dir,"kernel-2.13.3", + [{create_dir,"include", + [{copy_file,[...]},{copy_file,...},{...}]}]}, + {archive,"stdlib-1.16.3.ez",[], + [{create_dir,"stdlib-1.16.3",[{...}|...]}]}, + {create_dir,"stdlib-1.16.3", + [{create_dir,"include",[{...}|...]}]}]}]} + + + +3> TargetDir = "my_target_dir". +"my_target_dir" +4> reltool:eval_target_spec(Spec, code:root_dir(), TargetDir). +{error,"/clearcase/otp/tools/reltool/my_target_dir: no such file or directory"} +5> file:make_dir("my_target_dir"). +ok +6> reltool:eval_target_spec(Spec, code:root_dir(), TargetDir). +ok +7> file:list_dir(TargetDir). +{ok,["lib","erts-5.7.3","usr","Install","misc","bin","releases"]} +8> file:list_dir(filename:join([TargetDir,"lib"])). +{ok,["stdlib-1.16.3","stdlib-1.16.3.ez","kernel-2.13.3", + "kernel-2.13.3.ez","hipe-3.7.3.ez","erts-5.7.3.ez", + "crypto-1.6.1","crypto-1.6.1.ez","compiler-4.6.3.ez"]} +9> file:make_dir("yet_another_target_dir"). +ok +10> reltool:create_target(Config, "yet_another_target_dir"). +ok + </pre> + + </section> +</chapter> diff --git a/lib/reltool/doc/src/reltool_intro.xml b/lib/reltool/doc/src/reltool_intro.xml new file mode 100644 index 0000000000..54bc991da8 --- /dev/null +++ b/lib/reltool/doc/src/reltool_intro.xml @@ -0,0 +1,98 @@ +<?xml version="1.0" encoding="ISO-8859-1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Introduction</title> + <prepared>Håkan Mattsson</prepared> + <responsible>Håkan Mattsson</responsible> + <docno></docno> + <approved>Håkan Mattsson</approved> + <checked></checked> + <date></date> + <rev>%VSN%</rev> + <file>reltool_intro.xml</file> + </header> + <p><c>Reltool</c> is a release management tool. It analyses a given + Erlang/OTP installation and determines various dependencies between + applications. The <c>graphical</c> frontend depicts the dependencies and + enables interactive customization of a target system. The backend provides a + <c>batch</c> interface for generation of customized target systems.</p> + + <section> + <title>Scope and Purpose</title> + <p>This manual describes the Reltool application, as a component of the + Erlang/Open Telecom Platform development environment. It is assumed that + the reader is familiar with the Erlang Development Environment, which is + described in a separate User's Guide.</p> + </section> + + <section> + <title>Prerequisites</title> + <p>The following prerequisites is required for understanding the material + in the Reltool User's Guide:</p> + <list type="bulleted"> + <item> + <p>familiarity with Erlang/OTP system principles and Erlang/OTP design + principles</p> + </item> + </list> + <p>The application requires Erlang/OTP release R13B02 or later.</p> + </section> + + <section> + <title>About This Manual</title> + <p>In addition to this introductory chapter, the Reltool User's Guide + contains the following chapters:</p> + <list type="bulleted"> + <item> + <p>Chapter 2: "Usage" describes the architecture + and typical usage of the application.</p> + </item> + <item> + <p>Chapter 3: "Examples" gives some usage examples</p> + </item> + </list> + </section> + + <section> + <title>Where to Find More Information</title> + <p>Refer to the following documentation for more information about Reltool + and about the Erlang/OTP development system:</p> + <list type="bulleted"> + <item> + <p>the Reference Manual of <c>Reltool</c></p> + </item> + <item> + <p>the Erlang/OTP <c>System Principles</c></p> + </item> + <item> + <p>the Erlang/OTP <c>Design Principles</c></p> + </item> + <item> + <p>Programming Erlang: Software for a Concurrent World (2007), + Pragmatic Bookshelf, ISBN13: 9781934356005.</p> + </item> + </list> + </section> +</chapter> diff --git a/lib/reltool/doc/src/reltool_usage.xml b/lib/reltool/doc/src/reltool_usage.xml new file mode 100644 index 0000000000..885828d1f0 --- /dev/null +++ b/lib/reltool/doc/src/reltool_usage.xml @@ -0,0 +1,393 @@ +<?xml version="1.0" encoding="ISO-8859-1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2009</year> + <year>2009</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + 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. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Usage</title> + <prepared>Håkan Mattsson</prepared> + <responsible>Håkan Mattsson</responsible> + <docno></docno> + <approved>Håkan Mattsson</approved> + <checked></checked> + <date></date> + <rev>%VSN%</rev> + <file>reltool_usage.xml</file> + </header> + + <section> + <title>Overview</title> + <p>This document focuses on the graphical parts of the tool. The + concepts are explained in the reference manual for the module + <c>reltool</c>.</p> + </section> + + <section> + <title>System window</title> + <p>The system window is started with the function + <c>reltool:start/1</c>. At startup the tool will process the all + <c>beam</c> files and <c>app</c> files in order to find out dependencies + between applications and their modules. Once all this information has been + derived, it will be possible to explore the tool.</p> + + <p>The system window consists of four main pages (tabs):</p> + + <list> + <item>Libraries + </item> + <item>System settings + </item> + <item>Applications + </item> + <item>Releases + </item> + </list> + + <p>Click on a name tag to display its page.</p> + + <section> + <title>Libraries</title> + <p>On the library page it is possible to control which sources + that the tool will use. The page is organized as a tree which + can be expanded and collapsed by clicking on the little symbol + in the beginning of the expandable/collapsible lines.</p> + + <p>The <c>Root directory</c> can be edited by selecting the + line where the path of the root directory is displayed and + clicking with the right mouse button. Choose edit in the menu + that pops up. </p> + + <p>Library directories can be added, edited or deleted. This + is done by selecting the line where the path to a library + directory is displayed and clicking with the right mouse + button. Choose add, edit or delete in the menu that pops + up. New library directories can also be added by selecting the + line <c>Library directories</c> and clicking with the right + mouse button. Choose add in the menu that pops up.</p> + + <p>Escript files can be added, edited or deleted. This is done + by selecting the line where the path to an escript file is + displayed and clicking with the right mouse button. Choose + add, edit or delete in the menu that pops up. New escripts can + also be added by selecting the line <c>Escript files</c> and + clicking with the right mouse button. Choose add in the menu + that pops up.</p> + + <p>When libraries and escripts are expanded, the names of + their contained applications will be displayed. Double click + on an application name to launch an application window.</p> + </section> + + <section> + <title>System settings</title> + <p>On the system settings page it is possible to control some + global settings that are used as defaults for all + applications. Set the <c>Application inclusion policy</c> to + <c>include</c> to include all applications that not are + explicitly excluded. See <c>incl_cond</c> (application + inclusion) and <c>mod_cond</c> (module inclusion) in the + reference manual for the module <c>reltool</c> for more + info.</p> + <p>The system settings page is rather incomplete.</p> + </section> + + <section> + <title>Applications</title> + <p>There are four categories of applications on the + applications page. <c>Included</c> contains applications that + are explicitly included. <c>Excluded</c> contains applications + that are explicitly excluded. <c>Derived</c> contains + applications that either are used directly by explicitly + included applications or by other derived + applications. <c>Available</c> contains the remaining + applications.</p> + + <p>Select one or more applications and click on a button + directly below the application column to change application + category. For example, select an available application and + click on its tick button to move the application to the + included category. Clicking on the tick symbol for included + applications will move the application back to the available + category. The tick is undone.</p> + + <p>The symbols in front of the application names are intended + to describe the status of the application. There are error + symbols and warning symbols that means that there are + something that needs attention. The tick symbol means that the + application is included or derived and no problem has been + detected. The cross symbol means that the application is + excluded or available and no problem has been + detected. Applications with error symbols are listed first in + each category, then comes the warnings and the normal ones + (ticks and crosses) are found at the end.</p> + + <p>Double click on an application to launch its application + window.</p> + </section> + + <section> + <title>Releases</title> + <p>The releases page is incomplete and very experimental.</p> + </section> + + <section> + <title>File menu</title> + + <list> + <item> + <p><c>Display application dependency graph</c> - Launches an + application force graph window. All included and derived + applications and their dependencies will be shown in a + graph.</p> + </item> + <item> + <p><c>Display module dependency graph</c> - Launch a module + force graph window. All included and derived modules and + their dependencies will be shown in a graph.</p> + </item> + <item> + <p><c>Reset configuration to default</c></p> + </item> + <item> + <p><c>Undo configuration (toggle)</c></p> + </item> + <item> + <p><c>Load configuration</c> - Loads a new configuration from file.</p> + </item> + <item> + <p><c>Save configuration</c> - Saves the current + configuration to file. Normally, only the explictit + configuration parameters with values that differs from their + defaults are saved. But the configuration with or without + default values and with or without derived values may also + be saved.</p> + </item> + <item> + <p><c>Generate rel, script and boot files</c></p> + </item> + <item> + <p><c>Generate target system</c></p> + </item> + <item> + <p><c>Close</c> - Close the system window and all its subwindows.</p> + </item> + </list> + + </section> + + <section> + <title>Dependencies between applications or modules displayed as a graph</title> + + <p>The dependency graph windows are launched from the file menu + in the system window. The graph depicts all included and derived + applications/modules and their dependencies.</p> + + <p>It is possible to perform some limited manipulations of the + graph. Nodes can be moved, selected, locked or deleted. Move a + single node or the entire graph by moving the mouse while the + left mouse button is pressed. A node is can be locked into a fix + position by holding down the shift button when the left mouse + button is released. Select several nodes by moving the mouse + while the control key and the left mouse button i + pressed. Selected nodes can be locked, unlocked or deleted by + klicking on a suitable button.</p> + + <p>The algorithm that is used to draw a graph with as few + crossed links as possible is called force graph. A force graph + consists of nodes and directed link between nodes. Each node is + associated with a repulsive force that pushes nodes away from + each other. This force can be adjusted with the left slider or + with the mouse wheel. Each link is associated with an attractive + force that pulls the nodes nearer each other. This force can be + adjusted with the right slider. If this force becomes to strong, + the graph will be unstable. The third parameter that can be + adjusted is the length of the links. It is adjusted with the + middle slider.</p> + + <p>The <c>Freeze</c> button starts/stops the redrawing of the + graph. <c>Reset</c> moves the graph to the middle of the window + and resets all graph settings to default, with the exception of + deleted nodes.</p> + + </section> + + </section> + + <section> + <title>Application window</title> + <p>The application window is started by double clicking on an + application name. The application window consists of four + pages (tabs):</p> + + <list> + <item>Application settings + </item> + <item>Modules + </item> + <item>Application dependencies + </item> + <item>Module dependencies + </item> + </list> + + <p>Click on a name tag to display its page.</p> + + <section> + <title>Application settings</title> + <p>Select version of the application in the <c>Source selection + policy</c> part of the page. By default the latest version of the + application is selected, but it is possible to override this by + explicitly select another version.</p> + + <p>By default the <c>Application inclusion policy</c> on system + level is used for all applications. Set the value to + <c>include</c> if you want to explicitly include one particular + application. Set it to <c>exclude</c> if you want to exclude the + application despite that it is used by another (explicitly or + implicitly) included application. <c>derived</c> means that the + application automatically will be included if some other + (explicitly or implicitly) included application uses it.</p> + + <p>By default the <c>Module inclusion policy</c> on system level + is used for all applications. Set it to <c>derived</c> if you only + want actually used modules to be included. Set it to <c>app</c> if + you, besides derived modules, also want the modules listed in the + app file to be included. Set it to <c>ebin</c> if you, besides + derived modules, also want the modules that exists as beam files + on the ebin directory to be included. Set it to <c>all</c> if you + want all modules to be included, that is the union of modules + found on the ebin directory and listed in the app file.</p> + + <p>The application settings page is rather incomplete.</p> + </section> + + <section> + <title>Modules</title> + + <p>There are four categories of modules on the modules + page. <c>Included</c> contains modules that are explicitly + included. <c>Excluded</c> contains modules that are explicitly + excluded. <c>Derived</c> contains modules that either are used + directly by explicitly included modules or by other derived + modules. <c>Available</c> contains the remaining modules.</p> + + <p>Select one or more modules and click on a button directly + below the module column to change module category. For + example, select an available module and click on its tick + button to move the module to the included category. Clicking + on the tick symbol for included modules will move the + module back to the available category. The tick is + undone.</p> + + <p>The symbols in front of the module names are intended to + describe the status of the module. There are error symbols + and warning symbols that means that there are something that needs + attention. The tick symbol means that the module is included + or derived and no problem has been detected. The cross symbol + means that the module is excluded or available and no problem + has been detected. Modules with error symbols are listed + first in each category, then comes the warnings and the normal + ones (ticks and crosses) are found at the end.</p> + + <p>Double click on an module to launch its module window.</p> + + </section> + + <section> + <title>Application dependencies</title> + <p>There are four categories of applications on the <c>Application + dependencies</c> page. If the application is used by other + applications, these are listed under <c>Used by</c>. If the + application requires other applications be started before it can + be started, these are listed under <c>Required</c>. These + applications are listed in the <c>applications</c> part of the + <c>app</c> file. If the application includes other applications, + these are listed under <c>Included</c>. These applications are + listed in the <c>included_applications</c> part of the <c>app</c> + file. If the application uses modules other applications, these + are listed under <c>Uses</c>.</p> + + <p>Double click on an application name to launch an application window.</p> + + </section> + + <section> + <title>Module dependencies</title> + + <p>There are two categories of modules on the <c>Module + dependencies</c> page. If the module is used by other modules, + these are listed under <c>Modules used by others</c>. If the + module uses modules other modules, these are listed under <c>Used + modules</c>.</p> + + <p>Double click on an module name to launch a module window.</p> + + </section> + + </section> + + <section> + <title>Module window</title> + + <p>The module window is started by double clicking on an module + name. The module window consists initially of two pages (tabs):</p> + + <list> + <item>Dependencies + </item> + <item>Code + </item> + </list> + + <p>Click on a name tag to display its page.</p> + + <section> + <title>Dependencies</title> + + <p>There are two categories of modules on the <c>Dependencies</c> + page. If the module is used by other modules, these are listed + under <c>Modules used by others</c>. If the module uses modules + other modules, these are listed under <c>Used modules</c>.</p> + + <p>Double click on an module name to launch a module window.</p> + + </section> + + <section> + <title>Code</title> + + <p>On the <c>Code</c> page the Erlang source code is displayed. It + is possible to search forwards and backwards for text in the + module. Enter a regular expression in the <c>Find</c> field and + press enter. It is also possible to goto a certain line on the + module. The <c>Back</c> button can be used to go back to the + previous position.</p> + + <p>Put the marker on a function name and double click to go to the + definition of the function. If the function is defined in another + module, that module will be loaded and added to the page list. + </p> + </section> + + </section> + +</chapter> diff --git a/lib/reltool/doc/src/user_guide.gif b/lib/reltool/doc/src/user_guide.gif Binary files differnew file mode 100644 index 0000000000..e6275a803d --- /dev/null +++ b/lib/reltool/doc/src/user_guide.gif diff --git a/lib/reltool/doc/src/warning.gif b/lib/reltool/doc/src/warning.gif Binary files differnew file mode 100644 index 0000000000..96af52360e --- /dev/null +++ b/lib/reltool/doc/src/warning.gif |
