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} | {er‐
25                 ror,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 re‐
32              leases. The instructions are used by  release_handler  when  in‐
33              stalling 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 lo‐
37              cated 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, ap‐
50                  plications 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 up‐
60              grade files App.appup, sorted in the same order as when generat‐
61              ing  a boot script, see make_script/1,2. High-level instructions
62              are translated into low-level instructions  and  the  result  is
63              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 en‐
78              sures that a complete reboot of the system is done when the sys‐
79              tem 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_emulator_up‐
83              grade  is  issued.  For  more information about this, see Design
84              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,Module,Er‐
90              ror}. Warnings and errors can be converted to strings by calling
91              Module:format_warning(Warnings) or Module:format_error(Error).
92
93              If  option  noexec  is  specified, the function returns the same
94              values as for silent but no relup file is created.
95
96              If option warnings_as_errors is specified, warnings are  treated
97              as errors.
98
99       make_script(Name) -> Result
100       make_script(Name, [Opt]) -> Result
101
102              Types:
103
104                 Name = string()
105                 Opt  = src_tests | {path,[Dir]} | local | {variables,[Var]} |
106                 exref | {exref,[App]}] | silent | {outdir,Dir}  |  no_dot_er‐
107                 lang  |  no_warn_sasl  |  warnings_as_errors  | {script_name,
108                 Name}
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, unless the {script_name, ScriptName} option
120              is  given,  in  which  case  the names are ScriptName.script and
121              ScriptName.boot The boot file specifies which code to be  loaded
122              and  which  applications  to  be started when the Erlang runtime
123              system is started. See script(4).
124
125              The release resource file Name.rel is read  to  determine  which
126              applications  are included in the release. Then the relevant ap‐
127              plication resource files App.app are  read  to  determine  which
128              modules  to be loaded, and if and how the applications are to be
129              started. (Keys modules and mod, see app(4).
130
131              By default, the boot script and boot file  are  located  in  the
132              same  directory as Name.rel. That is, in the current working di‐
133              rectory unless Name contains a path. If option  {outdir,Dir}  is
134              specified, they are located in Dir instead.
135
136              The correctness of each application is checked as follows:
137
138                * The  version of an application specified in the .rel file is
139                  to be the same as the version specified in the .app file.
140
141                * There are to be no undefined applications, that  is,  depen‐
142                  dencies  to  applications  that  are not included in the re‐
143                  lease. (Key applications in the .app file).
144
145                * There are to be no circular dependencies among the  applica‐
146                  tions.
147
148                * There are to be no duplicated modules, that is, modules with
149                  the same name but belonging to different applications.
150
151                * If option src_tests is specified, a warning is issued if the
152                  source code for a module is missing or is newer than the ob‐
153                  ject code.
154
155              The applications are sorted according to  the  dependencies  be‐
156              tween the applications. Where there are no dependencies, the or‐
157              der in the .rel file is kept.
158
159              The function fails if  the  mandatory  applications  Kernel  and
160              STDLIB  are  not  included  in the .rel file and have start type
161              permanent (which is default).
162
163              If SASL is not included as an application in the  .rel  file,  a
164              warning  is  issued  because such a release cannot be used in an
165              upgrade. To turn off this warning, add option no_warn_sasl.
166
167              All files are searched for in the current path.  It  is  assumed
168              that  the .app and .beam files for an application are located in
169              the same directory. The .erl files are also assumed  to  be  lo‐
170              cated in this directory, unless it is an ebin directory in which
171              case they can be located in the corresponding src directory.
172
173              If option {path,[Dir]} is specified, this path  is  appended  to
174              the  current path. A directory in the path can be specified with
175              a wildcard *, this is expanded to all matching directories.  Ex‐
176              ample: "lib/*/ebin".
177
178              In  the  generated  boot  script all application directories are
179              structured as App-Vsn/ebin. They are assumed to  be  located  in
180              $ROOT/lib,  where  $ROOT  is the root directory of the installed
181              release. If option local is specified,  the  actual  directories
182              where  the  applications  were found are used instead. This is a
183              useful way to test a generated boot script locally.
184
185              Option variables can be used to specify an  installation  direc‐
186              tory  other  than  $ROOT/lib  for some of the applications. If a
187              variable {VarName,Prefix} is specified  and  an  application  is
188              found  in  a directory Prefix/Rest/App[-Vsn]/ebin, this applica‐
189              tion gets the path VarName/Rest/App-Vsn/ebin in the boot script.
190              If  an application is found in a directory Prefix/Rest, the path
191              is VarName/Rest/App-Vsn/ebin. When starting  Erlang,  all  vari‐
192              ables VarName are given values using command-line flag boot_var.
193
194              Example: If option {variables,[{"TEST","lib"}]} is specified and
195              myapp.app is found in lib/myapp/ebin, the path to this  applica‐
196              tion in the boot script is "$TEST/myapp-1/ebin". If myapp.app is
197              found in lib/test, the path is $TEST/test/myapp-1/ebin.
198
199              The checks performed before the boot script is generated can  be
200              extended  with  some cross reference checks by specifying option
201              exref. These checks are performed with the Xref tool. All appli‐
202              cations,  or  the applications specified with {exref,[App]}, are
203              checked by Xref and warnings are issued for calls  to  undefined
204              functions.
205
206              By default, errors and warnings are printed to tty and the func‐
207              tion returns ok or error. If option  silent  is  specified,  the
208              function  instead  returns  {ok,Module,Warnings}  or {error,Mod‐
209              ule,Error}. Warnings and errors can be converted to  strings  by
210              calling   Module:format_warning(Warnings)  or  Module:format_er‐
211              ror(Error).
212
213              If option warnings_as_errors is specified, warnings are  treated
214              as errors.
215
216              If  option  no_dot_erlang  is specified, the instruction to load
217              the .erlang file during boot is not included.
218
219       make_tar(Name) -> Result
220
221       make_tar(Name, Opts) -> Result
222
223              Types:
224
225                 Name = string()
226                 Opts = [Opt]
227                 Opt =
228                     {dirs, [IncDir]} |
229                     {path, [Dir]} |
230                     {variables, [Var]} |
231                     {var_tar, VarTar} |
232                     {erts, Dir} |
233                     erts_all | src_tests | exref |
234                     {exref, [App]} |
235                     silent |
236                     {outdir, Dir} |
237                     no_warn_sasl | warnings_as_errors |
238                     {extra_files, ExtraFiles}
239                 Dir = file:filename_all()
240                 IncDir = src | include | atom()
241                 Var = {VarName, PreFix}
242                 VarName = PreFix = string()
243                 VarTar = include | ownfile | omit
244                 App = atom()
245                 Result =
246                     ok | error |
247                     {ok, Module :: module(), Warnings :: term()} |
248                     {error, Module :: module(), Error :: term()}
249                 ExtraFiles = [{NameInArchive, file:filename_all()}]
250                 NameInArchive = string()
251
252              Creates a release package file Name.tar.gz. This  file  must  be
253              uncompressed  and  unpacked  on  the  target  system  using  re‐
254              lease_handler before the new release can be installed.
255
256              The release resource file Name.rel is read  to  determine  which
257              applications  are included in the release. Then the relevant ap‐
258              plication resource files App.app are read to determine the  ver‐
259              sion  and modules of each application (keys vsn and modules, see
260              app(4)).
261
262              By default, the release package file is located in the same  di‐
263              rectory  as  Name.rel. That is, in the current working directory
264              unless Name contains a path. If option  {outdir,Dir}  is  speci‐
265              fied, it is located in Dir instead.
266
267              If  SASL  is  not included as an application in the .rel file, a
268              warning is issued because such a release cannot be  used  in  an
269              upgrade. To turn off this warning, add option no_warn_sasl.
270
271              By   default,  the  release  package  contains  the  directories
272              lib/App-Vsn/ebin and lib/App-Vsn/priv for each included applica‐
273              tion.  If  more  directories  are to be included, option dirs is
274              specified, for example, {dirs,[src,examples]}.
275
276              All these files are searched for in the current path. If  option
277              {path,[Dir]}  is specified, this path is appended to the current
278              path. Wildcard * is expanded to all matching directories.  Exam‐
279              ple: "lib/*/ebin".
280
281              If  the  {extra_files,  ExtraFiles} option is given then the Ex‐
282              traFiles are added to the tarball after everything  else  to  be
283              included  has been added. The ExtraFiles list is a list of files
284              or directories in the same format as the  add_type()  tuple  for
285              erl_tar:add/3,4
286
287              Option  variables  can be used to specify an installation direc‐
288              tory other than lib for some of the  applications.  If  variable
289              {VarName,Prefix} is specified and an application is found in di‐
290              rectory Prefix/Rest/App[-Vsn]/ebin, this application  is  packed
291              into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.
292
293              Example: If option {variables,[{"TEST","lib"}]} is specified and
294              myapp.app is located in lib/myapp-1/ebin, application  myapp  is
295              included in TEST.tar.gz:
296
297              % tar tf TEST.tar
298              myapp-1/ebin/myapp.app
299
300              Option  {var_tar,VarTar}  can  be used to specify if and where a
301              separate package is to be stored. In this option VarTar  is  one
302              of the following:
303
304                include:
305                  Each separate (variable) package is included in the main Re‐
306                  leaseName.tar.gz file. This is the default.
307
308                ownfile:
309                  Each separate (variable) package is generated as a  separate
310                  file in the same directory as the ReleaseName.tar.gz file.
311
312                omit:
313                  No  separate (variable) packages are generated. Applications
314                  that are found underneath a variable directory are ignored.
315
316              A directory releases is also included in  the  release  package,
317              containing Name.rel and a subdirectory RelVsn. RelVsn is the re‐
318              lease version as specified in Name.rel.
319
320              releases/RelVsn contains the boot script  Name.boot  renamed  to
321              start.boot  and,  if  found,  the  files relup and sys.config or
322              sys.config.src. These files are searched for in the same  direc‐
323              tory  as  Name.rel, in the current working directory, and in any
324              directories specified using option path. In the case of sys.con‐
325              fig it is not included if sys.config.src is found.
326
327              If  the  release package is to contain a new Erlang runtime sys‐
328              tem, the erts-ErtsVsn/bin directory  of  the  specified  runtime
329              system  {erts,Dir} is copied to erts-ErtsVsn/bin. Some erts exe‐
330              cutables are not copied by default, if you want to  include  all
331              executables you can give the erts_all option.
332
333              All  checks  with  function make_script are performed before the
334              release package is created. Options src_tests and exref are also
335              valid here.
336
337              The return value and the handling of errors and warnings are the
338              same as described for make_script.
339
340       script2boot(File) -> ok | error
341
342              Types:
343
344                 File = string()
345
346              The Erlang runtime system requires  that  the  contents  of  the
347              script  used  to  boot  the system is a binary Erlang term. This
348              function transforms the File.script  boot  script  to  a  binary
349              term, which is stored in the File.boot file.
350
351              A boot script generated using make_script is already transformed
352              to the binary form.
353

SEE ALSO

355       app(4),  appup(4),  erl(1),   rel(4),   release_handler(3),   relup(4),
356       script(4)
357
358
359
360Ericsson AB                        sasl 4.2                        systools(3)
Impressum