systools(3erl)						     Erlang Module Definition						    systools(3erl)

NAME

       systools - A Set of Release Handling Tools.

DESCRIPTION

       This module contains functions to generate boot scripts ( .boot , .script ), release upgrade scripts ( relup ), and release packages.

EXPORTS

       make_relup(Name, UpFrom, DownTo) -> Result
       make_relup(Name, UpFrom, DownTo, [Opt]) -> Result

	      Types  Name = string()
		     UpFrom = DownTo = [Name | {Name,Descr}]
		     Descr = term()
		     Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir}
		     Dir = string()
		     Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}
		     Relup - see relup(5)
		     Module = atom()
		     Warnings = Error = term()

	      Generates  a  release  upgrade  file  relup  containing a script which describes how to upgrade the system from a number of previous
	      releases, and how to downgrade to a number of previous releases. The script is used by release_handler when installing a new version
	      of a release in run-time.

	      By  default,  relup  is  placed  in  the	current  working directory. If the option {outdir,Dir} is provided, relup is placed in Dir
	      instead.

	      The release resource file Name.rel is compared with all release resource files Name2.rel specified in UpFrom and DownTo .  For  each
	      such pair, it is deducted:

		* Which applications should be deleted, that is applications which are listed in Name.rel but not in Name2.rel .

		* Which applications should be added, that is applications which are listed in Name2.rel but not in Name.rel .

		* Which  applications should be upgraded/downgraded, that is applications listed in both Name.rel and Name2.rel , but with differ-
		  ent versions.

		* If the emulator needs to be restarted after upgrading or downgrading, that is if the ERTS version differs between  Name.rel  and
		  Name2.rel .

	      Instructions  for  this are added to the relup script in the above order. Instructions for upgrading or downgrading between applica-
	      tion versions are fetched from the relevant application upgrade files App.appup , sorted in the same order as when generating a boot
	      script,  see make_script/1,2 . High-level instructions are translated into low-level instructions and the result is printed to relup
	      .

	      The optional Descr parameter is included as-is in the relup script, see relup(5) . Defaults to the empty list.

	      All the files are searched for in the code path. It is assumed that the .app and .appup file for an application is  located  in  the
	      same directory.

	      If the option {path,[Dir]} is provided, this path is appended to the current path. The wildcard * is expanded to all matching direc-
	      tories. Example: lib/*/ebin .

	      If the restart_emulator option is supplied, a low-level instruction to restart the emulator is appended to the relup  scripts.  This
	      ensures that a complete reboot of the system is done when the system is upgraded or downgraded.

	      By  default,  errors  and  warnings  are printed to tty and the function returns ok or error . If the option silent is provided, the
	      function instead returns {ok,Relup,Module,Warnings} where Relup is the release upgrade script, or it returns {error,Module,Error}  .
	      Warnings and errors can be converted to strings by calling Module:format_warning(Warnings) or Module:format_error(Error) .

	      If the option noexec is provided, the function returns the same values as for silent but no relup file is created.

       make_script(Name) -> Result
       make_script(Name, [Opt]) -> Result

	      Types  Name = string()
		     Opt = no_module_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent | {outdir,Dir}
		     Dir = string()
		     Var = {VarName,Prefix}
		     VarName = Prefix = string()
		     App = atom()
		     Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}
		     Module = atom()
		     Warnings = Error = term()

	      Generates  a  boot script Name.script and its binary version, the boot file Name.boot . The boot file specifies which code should be
	      loaded and which applications should be started when the Erlang runtime system is started. See script(5) .

	      The release resource file Name.rel is read to find out which applications are included in the release. Then the relevant application
	      resource	files  App.app are read to find out which modules should be loaded and if and how the application should be started. (Keys
	      modules and mod , see app(5) ).

	      By default, the boot script and boot file are placed in the same directory as Name.rel . That is, in the current	working  directory
	      unless Name contains a path. If the option {outdir,Dir} is provided, they are placed in Dir instead.

	      The correctness of each application is checked:

		* The version of an application specified in the .rel file should be the same as the version specified in the .app file.

		* There  should  be  no  undefined applications, that is, dependencies to applications which are not included in the release. (Key
		  applications in .app file).

		* There should be no circular dependencies among the applications.

		* There should no duplicated modules, that is, modules with the same name but belonging to different applications.

		* A warning is issued if the source code for a module is missing or newer than the object code.
		  If the no_module_tests option is specified, this check is omitted.

	      The applications are sorted according to the dependencies between the applications. Where there are no dependencies,  the  order	in
	      the .rel file is kept.

	      All  files  are  searched  for in the current path. It is assumed that the .app and .beam files for an application is located in the
	      same directory. The .erl files are also assumed to be located in this directory, unless it is an ebin directory in which	case  they
	      may be located in the corresponding src directory.

	      If the option {path,[Dir]} is provided, this path is appended to the current path. A directory in the path can be given with a wild-
	      card * , this is expanded to all matching directories. Example: "lib/*/ebin" .

	      In the generated boot script all application directories are structured as App-Vsn/ebin and assumed to be  located  in  $ROOT/lib  ,
	      where $ROOT is the root directory of the installed release. If the local option is supplied, the actual directories where the appli-
	      cations were found are used instead. This is a useful way to test a generated boot script locally.

	      The variables option can be used to specify an installation directory other than $ROOT/lib for some of the applications. If a  vari-
	      able {VarName,Prefix} is specified and an application is found in a directory Prefix/Rest/App[-Vsn]/ebin , this application will get
	      the path VarName/Rest/App-Vsn/ebin in the boot script. If an application is found in a directory Prefix/Rest , the path will be Var-
	      Name/Rest/App-Vsn/ebin . When starting Erlang, all variables VarName are given values using the boot_var command line flag.

	      Example:	If  the  option {variables,[{"TEST","lib"}]} is supplied, and myapp.app is found in lib/myapp/ebin , then the path to this
	      application in the boot script will be  $TEST/myapp-1/ebin"  .  If  myapp.app  is  found	in  lib/test  ,  then  the  path  will	be
	      $TEST/test/myapp-1/ebin .

	      The  checks  performed  before the boot script is generated can be extended with some cross reference checks by specifying the exref
	      option. These checks are performed with the Xref tool. All applications, or the applications  specified  with  {exref,[App]}  ,  are
	      checked by Xref and warnings are generated for calls to undefined functions.

	      By  default,  errors  and  warnings  are printed to tty and the function returns ok or error . If the option silent is provided, the
	      function instead returns {ok,Module,Warnings} or {error,Module,Error} . Warnings and errors can be converted to strings  by  calling
	      Module:format_warning(Warnings) or Module:format_error(Error) .

       make_tar(Name) -> Result
       make_tar(Name, [Opt]) -> Result

	      Types  Name = string()
		     Opt  =  {dirs,[IncDir]}  |  {path,[Dir]}  |  {variables,[Var]}  |	{var_tar,VarTar}  | {erts,Dir} | no_module_tests | exref |
		     {exref,[App]} | silent | {outdir,Dir}
		     Dir = string()
		     IncDir = src | include | atom()
		     Var = {VarName,PreFix}
		     VarName = Prefix = string()
		     VarTar = include | ownfile | omit
		     Machine = atom()
		     App = atom()
		     Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}
		     Module = atom()
		     Warning = Error = term()

	      Creates a release package file Name.tar.gz . file. This file must be uncompressed and  unpacked  on  the	target	system	using  the
	      release_handler , before the new release can be installed.

	      The release resource file Name.rel is read to find out which applications are included in the release. Then the relevant application
	      resource files App.app are read to find out the version and modules of each application. (Keys vsn and modules , see app(5) ).

	      By default, the release package file is placed in the same directory as Name.rel . That is, in the current working directory  unless
	      Name contains a path. If the option {outdir,Dir} is provided, it is placed in Dir instead.

	      By  default,  the  release  package contains the directories lib/App-Vsn/ebin and lib/App-Vsn/priv for each included application. If
	      more directories, the option dirs is supplied. Example: {dirs,[src,examples]} .

	      All these files are searched for in the current path. If the option {path,[Dir]} is provided, this path is appended to  the  current
	      path. The wildcard * is expanded to all matching directories. Example: "lib/*/ebin" .

	      The  variables  option  can  be used to specify an installation directory other than lib for some of the applications. If a variable
	      {VarName,Prefix} is specified and an application is found in a directory	Prefix/Rest/App[-Vsn]/ebin  ,  this  application  will	be
	      packed into a separate VarName.tar.gz file as Rest/App-Vsn/ebin .

	      Example:	If  the  option {variables,[{"TEST","lib"}]} is supplied, and myapp.app is found in lib/myapp-1/ebin , the the application
	      myapp is included in TEST.tar.gz :

	      % tar tf TEST.tar
	      myapp-1/ebin/myapp.app

	      The {var_tar,VarTar} option can be used to specify if and where a separate package should be stored. In this option, VarTar is:

		* include . Each separate (variable) package is included in the main ReleaseName.tar.gz file. This is the default.

		* ownfile . Each separate (variable) package is generated as separate files in the same directory as the ReleaseName.tar.gz file.

		* omit . No separate (variable) packages are generated and applications which  are  found  underneath  a  variable  directory  are
		  ignored.

	      A  directory  called releases is also included in the release package, containing Name.rel and a subdirectory called RelVsn . RelVsn
	      is the release version as specified in Name.rel .

	      releases/RelVsn contains the boot script Name.boot renamed to start.boot and, if found, the files relup and sys.config . These files
	      are  searched  for  in the same directory as Name.rel , in the current working directory, and in any directories specified using the
	      path option.

	      If the release package should contain a new Erlang runtime system, the bin directory of the specified runtime system  {erts,Dir}	is
	      copied to erts-ErtsVsn/bin .

	      All  checks  performed  with  the  make_script function are performed before the release package is created. The no_module_tests and
	      exref options are also valid here.

	      The return value and the handling of errors and warnings are the same as described for make_script above.

       script2boot(File) -> ok | error

	      Types  File = string()

	      The Erlang runtime system requires that the contents of the script used to boot the system is a binary Erlang  term.  This  function
	      transforms the File.script boot script to a binary term which is stored in the file File.boot .

	      A boot script generated using the make_script function is already transformed to the binary form.

SEE ALSO

       app(5), appup(5), erl(1), rel(5), release_handler(3erl), relup(5), script(5)

Ericsson AB							   sasl 2.1.9.3 						    systools(3erl)