1systools(3)                Erlang Module Definition                systools(3)
2
3
4

NAME

6       systools - A Set of Release Handling Tools
7

DESCRIPTION

9       This  module  contains  functions  to  generate  boot  scripts  (.boot,
10       .script), a release upgrade file (relup), and release packages.
11

EXPORTS

13       make_relup(Name, UpFrom, DownTo) -> Result
14       make_relup(Name, UpFrom, DownTo, [Opt]) -> Result
15
16              Types:
17
18                 Name = string()
19                 UpFrom = DownTo = [Name | {Name,Descr}]
20                  Descr = term()
21                 Opt = {path,[Dir]} | restart_emulator |  silent  |  noexec  |
22                 {outdir,Dir} | warnings_as_errors
23                  Dir = string()
24                 Result   =   ok   |   error  |  {ok,Relup,Module,Warnings}  |
25                 {error,Module,Error}
26                  Relup, see relup(4)
27                  Module = atom()
28                  Warnings = Error = term()
29
30              Generates a release upgrade file relup  containing  instructions
31              for  upgrading  from  or  downgrading  to  one  or more previous
32              releases. The instructions  are  used  by  release_handler  when
33              installing a new version of a release in runtime.
34
35              By  default, relup file is located in the current working direc‐
36              tory. If option {outdir,Dir} is specified,  the  relup  file  is
37              located in Dir instead.
38
39              The  release resource file Name.rel is compared with all release
40              resource files Name2.rel, specified in UpFrom  and  DownTo.  For
41              each such pair, the following is deducted:
42
43                * Which  applications  to  be  deleted,  that is, applications
44                  listed in Name.rel but not in Name2.rel
45
46                * Which applications to be added, that is, applications listed
47                  in Name2.rel but not in Name.rel
48
49                * Which  applications  to  be  upgraded/downgraded,  that  is,
50                  applications listed in both Name.rel and Name2.rel but  with
51                  different versions
52
53                * If  the  emulator  needs  to be restarted after upgrading or
54                  downgrading, that is, if the ERTS  version  differs  between
55                  Name.rel and Name2.rel
56
57              Instructions  for  this are added to the relup file in the above
58              order. Instructions for upgrading or downgrading between  appli‐
59              cation  versions  are  fetched  from  the  relevant  application
60              upgrade files App.appup, sorted in the same order as when gener‐
61              ating  a  boot  script, see make_script/1,2. High-level instruc‐
62              tions are translated into low-level instructions and the  result
63              is printed to the relup file.
64
65              The  optional  Descr  parameter is included "as is" in the relup
66              file, see relup(4). Defaults to the empty list.
67
68              All the files are searched for in the code path. It  is  assumed
69              that the .app and .appup files for an application are located in
70              the same directory.
71
72              If option {path,[Dir]} is specified, this path  is  appended  to
73              the  current path. Wildcard * is expanded to all matching direc‐
74              tories, for example, lib/*/ebin.
75
76              If option restart_emulator is specified, a low-level instruction
77              to  restart  the  emulator  is  appended to the relup file. This
78              ensures that a complete reboot of the system is  done  when  the
79              system is upgraded or downgraded.
80
81              If  an  upgrade  includes a change from an emulator earlier than
82              OTP  R15  to  OTP  R15  or  later,  the  warning  pre_R15_emula‐
83              tor_upgrade  is  issued.  For  more  information about this, see
84              Design Principles in System Documentation.
85
86              By default, errors and warnings are printed to tty and the func‐
87              tion  returns  ok  or  error. If option silent is specified, the
88              function  instead  either  returns   {ok,Relup,Module,Warnings},
89              where   Relup  is  the  release  upgrade  file,  or  {error,Mod‐
90              ule,Error}. Warnings and errors can be converted to  strings  by
91              calling     Module:format_warning(Warnings)    or    Module:for‐
92              mat_error(Error).
93
94              If option noexec is specified, the  function  returns  the  same
95              values as for silent but no relup file is created.
96
97              If  option warnings_as_errors is specified, warnings are treated
98              as errors.
99
100       make_script(Name) -> Result
101       make_script(Name, [Opt]) -> Result
102
103              Types:
104
105                 Name = string()
106                 Opt = src_tests | {path,[Dir]} | local | {variables,[Var]}  |
107                 exref   |   {exref,[App]}]   |   silent   |   {outdir,Dir}  |
108                 no_dot_erlang | no_warn_sasl | warnings_as_errors
109                  Dir = string()
110                  Var = {VarName,Prefix}
111                  VarName = Prefix = string()
112                  App = atom()
113                 Result = ok |  error  |  {ok,Module,Warnings}  |  {error,Mod‐
114                 ule,Error}
115                  Module = atom()
116                  Warnings = Error = term()
117
118              Generates  a boot script Name.script and its binary version, the
119              boot file Name.boot. The boot file specifies which  code  to  be
120              loaded and which applications to be started when the Erlang run‐
121              time system is started. See script(4).
122
123              The release resource file Name.rel is read  to  determine  which
124              applications  are  included  in  the  release. Then the relevant
125              application resource files App.app are read to  determine  which
126              modules  to be loaded, and if and how the applications are to be
127              started. (Keys modules and mod, see app(4).
128
129              By default, the boot script and boot file  are  located  in  the
130              same  directory  as  Name.rel.  That  is, in the current working
131              directory unless Name contains a path. If option {outdir,Dir} is
132              specified, they are located in Dir instead.
133
134              The correctness of each application is checked as follows:
135
136                * The  version of an application specified in the .rel file is
137                  to be the same as the version specified in the .app file.
138
139                * There are to be no undefined applications, that  is,  depen‐
140                  dencies  to  applications  that  are  not  included  in  the
141                  release. (Key applications in the .app file).
142
143                * There are to be no circular dependencies among the  applica‐
144                  tions.
145
146                * There are to be no duplicated modules, that is, modules with
147                  the same name but belonging to different applications.
148
149                * If option src_tests is specified, a warning is issued if the
150                  source  code  for  a  module is missing or is newer than the
151                  object code.
152
153              The  applications  are  sorted  according  to  the  dependencies
154              between  the  applications. Where there are no dependencies, the
155              order in the .rel file is kept.
156
157              The function fails if  the  mandatory  applications  Kernel  and
158              STDLIB  are  not  included  in the .rel file and have start type
159              permanent (which is default).
160
161              If SASL is not included as an application in the  .rel  file,  a
162              warning  is  issued  because such a release cannot be used in an
163              upgrade. To turn off this warning, add option no_warn_sasl.
164
165              All files are searched for in the current path.  It  is  assumed
166              that  the .app and .beam files for an application are located in
167              the same directory. The  .erl  files  are  also  assumed  to  be
168              located  in  this  directory,  unless it is an ebin directory in
169              which case they can be located in the corresponding  src  direc‐
170              tory.
171
172              If  option  {path,[Dir]}  is specified, this path is appended to
173              the current path. A directory in the path can be specified  with
174              a  wildcard  *,  this  is  expanded to all matching directories.
175              Example: "lib/*/ebin".
176
177              In the generated boot script  all  application  directories  are
178              structured  as  App-Vsn/ebin.  They are assumed to be located in
179              $ROOT/lib, where $ROOT is the root directory  of  the  installed
180              release.  If  option  local is specified, the actual directories
181              where the applications were found are used instead.  This  is  a
182              useful way to test a generated boot script locally.
183
184              Option  variables  can be used to specify an installation direc‐
185              tory other than $ROOT/lib for some of  the  applications.  If  a
186              variable  {VarName,Prefix}  is  specified  and an application is
187              found in a directory Prefix/Rest/App[-Vsn]/ebin,  this  applica‐
188              tion gets the path VarName/Rest/App-Vsn/ebin in the boot script.
189              If an application is found in a directory Prefix/Rest, the  path
190              is  VarName/Rest/App-Vsn/ebin.  When  starting Erlang, all vari‐
191              ables VarName are given values using command-line flag boot_var.
192
193              Example: If option {variables,[{"TEST","lib"}]} is specified and
194              myapp.app  is found in lib/myapp/ebin, the path to this applica‐
195              tion in the boot script is "$TEST/myapp-1/ebin". If myapp.app is
196              found in lib/test, the path is $TEST/test/myapp-1/ebin.
197
198              The  checks performed before the boot script is generated can be
199              extended with some cross reference checks by  specifying  option
200              exref. These checks are performed with the Xref tool. All appli‐
201              cations, or the applications specified with  {exref,[App]},  are
202              checked  by  Xref and warnings are issued for calls to undefined
203              functions.
204
205              By default, errors and warnings are printed to tty and the func‐
206              tion  returns  ok  or  error. If option silent is specified, the
207              function instead  returns  {ok,Module,Warnings}  or  {error,Mod‐
208              ule,Error}.  Warnings  and errors can be converted to strings by
209              calling    Module:format_warning(Warnings)    or     Module:for‐
210              mat_error(Error).
211
212              If  option warnings_as_errors is specified, warnings are treated
213              as errors.
214
215              If option no_dot_erlang is specified, the  instruction  to  load
216              the .erlang file during boot is not included.
217
218       make_tar(Name) -> Result
219       make_tar(Name, [Opt]) -> Result
220
221              Types:
222
223                 Name = string()
224                 Opt  =  {dirs,[IncDir]}  | {path,[Dir]} | {variables,[Var]} |
225                 {var_tar,VarTar}  |  {erts,Dir}  |  src_tests   |   exref   |
226                 {exref,[App]}  |  silent  |  {outdir,Dir}  | | no_warn_sasl |
227                 warnings_as_errors
228                  Dir = string()
229                  IncDir = src | include | atom()
230                  Var = {VarName,PreFix}
231                  VarName = Prefix = string()
232                  VarTar = include | ownfile | omit
233                  Machine = atom()
234                  App = atom()
235                 Result = ok |  error  |  {ok,Module,Warnings}  |  {error,Mod‐
236                 ule,Error}
237                  Module = atom()
238                  Warning = Error = term()
239
240              Creates  a  release  package file Name.tar.gz. This file must be
241              uncompressed  and  unpacked   on   the   target   system   using
242              release_handler before the new release can be installed.
243
244              The  release  resource  file Name.rel is read to determine which
245              applications are included in  the  release.  Then  the  relevant
246              application  resource  files  App.app  are read to determine the
247              version and modules of each application (keys vsn  and  modules,
248              see app(4)).
249
250              By  default,  the  release  package  file is located in the same
251              directory as Name.rel. That is, in the current working directory
252              unless  Name  contains  a path. If option {outdir,Dir} is speci‐
253              fied, it is located in Dir instead.
254
255              If SASL is not included as an application in the  .rel  file,  a
256              warning  is  issued  because such a release cannot be used in an
257              upgrade. To turn off this warning, add option no_warn_sasl.
258
259              By  default,  the  release  package  contains  the   directories
260              lib/App-Vsn/ebin and lib/App-Vsn/priv for each included applica‐
261              tion. If more directories are to be  included,  option  dirs  is
262              specified, for example, {dirs,[src,examples]}.
263
264              All  these files are searched for in the current path. If option
265              {path,[Dir]} is specified, this path is appended to the  current
266              path.  Wildcard * is expanded to all matching directories. Exam‐
267              ple: "lib/*/ebin".
268
269              Option variables can be used to specify an  installation  direc‐
270              tory  other  than  lib for some of the applications. If variable
271              {VarName,Prefix} is specified and an  application  is  found  in
272              directory Prefix/Rest/App[-Vsn]/ebin, this application is packed
273              into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.
274
275              Example: If option {variables,[{"TEST","lib"}]} is specified and
276              myapp.app  is  located in lib/myapp-1/ebin, application myapp is
277              included in TEST.tar.gz:
278
279              % tar tf TEST.tar
280              myapp-1/ebin/myapp.app
281
282              Option {var_tar,VarTar} can be used to specify if  and  where  a
283              separate  package  is to be stored. In this option VarTar is one
284              of the following:
285
286                include:
287                  Each separate (variable) package is  included  in  the  main
288                  ReleaseName.tar.gz file. This is the default.
289
290                ownfile:
291                  Each  separate (variable) package is generated as a separate
292                  file in the same directory as the ReleaseName.tar.gz file.
293
294                omit:
295                  No separate (variable) packages are generated.  Applications
296                  that are found underneath a variable directory are ignored.
297
298              A  directory  releases  is also included in the release package,
299              containing Name.rel and a subdirectory  RelVsn.  RelVsn  is  the
300              release version as specified in Name.rel.
301
302              releases/RelVsn  contains  the  boot script Name.boot renamed to
303              start.boot and, if found, the  files  relup  and  sys.config  or
304              sys.config.src.  These files are searched for in the same direc‐
305              tory as Name.rel, in the current working directory, and  in  any
306              directories specified using option path. In the case of sys.con‐
307              fig it is not included if sys.config.src is found.
308
309              If the release package is to contain a new Erlang  runtime  sys‐
310              tem,   the   bin  directory  of  the  specified  runtime  system
311              {erts,Dir} is copied to erts-ErtsVsn/bin.
312
313              All checks with function make_script are  performed  before  the
314              release package is created. Options src_tests and exref are also
315              valid here.
316
317              The return value and the handling of errors and warnings are the
318              same as described for make_script.
319
320       script2boot(File) -> ok | error
321
322              Types:
323
324                 File = string()
325
326              The  Erlang  runtime  system  requires  that the contents of the
327              script used to boot the system is a  binary  Erlang  term.  This
328              function  transforms  the  File.script  boot  script to a binary
329              term, which is stored in the File.boot file.
330
331              A boot script generated using make_script is already transformed
332              to the binary form.
333

SEE ALSO

335       app(4),   appup(4),   erl(1),   rel(4),  release_handler(3),  relup(4),
336       script(4)
337
338
339
340Ericsson AB                       sasl 3.4.1                       systools(3)
Impressum