Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
systools(3)		   Erlang Module Definition		   systools(3)

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} |	warnings_as_errors
		  Dir =	string()
		 Result	 =  ok	|  error  |  {ok,Relup,Module,Warnings}	| {er-
		 ror,Module,Error}
		  Relup	- see relup(4)
		  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 ver-
	      sion 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 in-
	      stead.

	      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
		  different 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	appli-
	      cation versions are fetched from the  relevant  application  up-
	      grade files App.appup, sorted in the same	order as when generat-
	      ing 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(4). 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 di-
	      rectories. Example: lib/*/ebin.

	      If the restart_emulator option is	supplied, a low-level instruc-
	      tion 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.

	      If an upgrade includes a change from an  emulator	 earlier  than
	      OTP  R15	to  OTP	R15 or later, the warning pre_R15_emulator_up-
	      grade is issued. See  Design  Principles	for  more  information
	      about this.

	      By default, errors and warnings are printed to tty and the func-
	      tion 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,Er-
	      ror}. 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.

	      If  the  option  warnings_as_errors  is  provided,  warnings are
	      treated as errors.

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

	      Types:

		 Name =	string()
		 Opt = src_tests | {path,[Dir]}	| local	| {variables,[Var]}  |
		 exref	|  {exref,[App]}] | silent | {outdir,Dir} | no_dot_er-
		 lang |	no_warn_sasl | warnings_as_errors
		  Dir =	string()
		  Var =	{VarName,Prefix}
		  VarName = Prefix = string()
		  App =	atom()
		 Result	= ok |	error  |  {ok,Module,Warnings}	|  {error,Mod-
		 ule,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 Er-
	      lang runtime system is started. See script(4).

	      The release resource file	Name.rel is read to find out which ap-
	      plications are included in the release. Then the relevant	appli-
	      cation 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(4)).

	      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  pro-
	      vided, 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,	depen-
		  dencies to applications which	are not	included  in  the  re-
		  lease. (Key applications in .app file).

		* There	 should	be no circular dependencies among the applica-
		  tions.

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

		* If the src_tests option is specified,	a warning is issued if
		  the source code for a	module is missing or  newer  than  the
		  object code.

	      The  applications	 are  sorted according to the dependencies be-
	      tween the	applications. Where there are no dependencies, the or-
	      der in the .rel file is kept.

	      The  function will fail if the mandatory applications kernel and
	      stdlib are not included in the .rel file	and  have  start  type
	      permanent	(default).

	      If  sasl	is  not	included as an application in the .rel file, a
	      warning is emitted because such a	release	can not	be used	in  an
	      upgrade. To turn off this	warning, add the option	no_warn_sasl.

	      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 lo-
	      cated 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
	      wildcard	*, this	is expanded to all matching directories. Exam-
	      ple: "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	applications 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 di-
	      rectory other than $ROOT/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  applica-
	      tion  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 VarName/Rest/App-Vsn/ebin. When starting Er-
	      lang, 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 un-
	      defined functions.

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

	      If  the  option  warnings_as_errors  is  provided,  warnings are
	      treated as errors.

	      If the option no_dot_erlang is provided, the instruction to load
	      the .erlang file during boot is NOT included.

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

	      Types:

		 Name =	string()
		 Opt  =	 {dirs,[IncDir]}  | {path,[Dir]} | {variables,[Var]} |
		 {var_tar,VarTar}  |  {erts,Dir}  |  src_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,Mod-
		 ule,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 re-
	      lease_handler, before the	new release can	be installed.

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

	      By default, the release package file is placed in	the  same  di-
	      rectory  as  Name.rel. That is, in the current working directory
	      unless Name contains a path. If the option {outdir,Dir} is  pro-
	      vided, 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 applica-
	      tion. If more directories, the option dirs is supplied. Example:
	      {dirs,[src,examples]}.

	      All these	files are searched for in the current path. If the op-
	      tion {path,[Dir]}	is provided, this path is appended to the cur-
	      rent path. The wildcard *	is expanded to all  matching  directo-
	      ries. Example: "lib/*/ebin".

	      The  variables option can	be used	to specify an installation di-
	      rectory other than 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
	      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  Release-
		  Name.tar.gz file.

		* omit.	No separate (variable) packages	are generated and  ap-
		  plications  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 us-
	      ing the path option.

	      If the release package should contain a new Erlang runtime  sys-
	      tem,   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 src_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  al-
	      ready transformed	to the binary form.

SEE ALSO
       app(4),	 appup(4),   erl(1),   rel(4),	release_handler(3),  relup(4),
       script(4)

Ericsson AB			  sasl 2.4.1			   systools(3)

NAME | DESCRIPTION | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=systools&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help