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), a release upgrade file	(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  instructions
	      for  upgrading  from  or downgrading to one or more previous re-
	      leases. The instructions are used	by  release_handler  when  in-
	      stalling a new version of	a release in runtime.

	      By  default, relup file is located in the	current	working	direc-
	      tory. If option {outdir,Dir} is specified, the relup file	is lo-
	      cated 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, the following is deducted:

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

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

		* Which	 applications  to be upgraded/downgraded, that is, ap-
		  plications 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 file 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 the relup file.

	      The  optional  Descr  parameter is included "as is" in the relup
	      file, 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 files for an application	are located in
	      the same directory.

	      If option	{path,[Dir]} is	specified, this	path  is  appended  to
	      the  current path. Wildcard * is expanded	to all matching	direc-
	      tories, for example, lib/*/ebin.

	      If option	restart_emulator is specified, a low-level instruction
	      to  restart the emulator is appended to the relup	file. This en-
	      sures that a complete reboot of the system is done when the sys-
	      tem 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.  For  more information	about this, see	Design
	      Principles in System Documentation.

	      By default, errors and warnings are printed to tty and the func-
	      tion  returns  ok	 or  error. If option silent is	specified, the
	      function	instead	 either	 returns   {ok,Relup,Module,Warnings},
	      where  Relup  is	the release upgrade file, or {error,Module,Er-
	      ror}. Warnings and errors	can be converted to strings by calling
	      Module:format_warning(Warnings) or Module:format_error(Error).

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

	      If option	warnings_as_errors is specified, 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 to be
	      loaded and which applications to be started when the Erlang run-
	      time system is started. See script(4).

	      The  release  resource  file Name.rel is read to determine which
	      applications are included	in the release.	Then the relevant  ap-
	      plication	 resource  files  App.app  are read to determine which
	      modules to be loaded, and	if and how the applications are	to  be
	      started. (Keys modules and mod, see app(4).

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

	      The correctness of each application is checked as	follows:

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

		* There	 are  to be no undefined applications, that is,	depen-
		  dencies to applications that are not	included  in  the  re-
		  lease. (Key applications in the .app file).

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

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

		* If option src_tests is specified, a warning is issued	if the
		  source code for a module is missing or is newer than the ob-
		  ject 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  fails  if	the  mandatory applications Kernel and
	      STDLIB are not included in the .rel file	and  have  start  type
	      permanent	(which is default).

	      If  SASL	is  not	included as an application in the .rel file, a
	      warning is issued	because	such a release cannot be  used	in  an
	      upgrade. To turn off this	warning, add 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 are 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	can be located in the corresponding src	directory.

	      If  option  {path,[Dir]}	is specified, this path	is appended to
	      the current path.	A directory in the path	can be specified  with
	      a	 wildcard *, this is expanded to all matching directories. Ex-
	      ample: "lib/*/ebin".

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

	      Option  variables	 can be	used to	specify	an installation	direc-
	      tory 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 gets	the path VarName/Rest/App-Vsn/ebin in the boot script.
	      If an application	is found in a directory	Prefix/Rest, the  path
	      is  VarName/Rest/App-Vsn/ebin.  When  starting Erlang, all vari-
	      ables VarName are	given values using command-line	flag boot_var.

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

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

	      By default, errors and warnings are printed to tty and the func-
	      tion  returns  ok	 or  error. If option silent is	specified, 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  option warnings_as_errors is specified, warnings are treated
	      as errors.

	      If option	no_dot_erlang is specified, 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}  | |	no_warn_sasl |
		 warnings_as_errors
		  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. This file must be
	      uncompressed  and	 unpacked  on  the  target  system  using  re-
	      lease_handler before the new release can be installed.

	      The  release  resource  file Name.rel is read to determine which
	      applications are included	in the release.	Then the relevant  ap-
	      plication	 resource files	App.app	are read to determine the ver-
	      sion and modules of each application (keys vsn and modules,  see
	      app(4)).

	      By  default, the release package file is located in the same di-
	      rectory as Name.rel. That	is, in the current  working  directory
	      unless  Name  contains  a	path. If option	{outdir,Dir} is	speci-
	      fied, it is located in Dir instead.

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

	      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	are to be  included,  option  dirs  is
	      specified, for example, {dirs,[src,examples]}.

	      All  these files are searched for	in the current path. If	option
	      {path,[Dir]} is specified, this path is appended to the  current
	      path.  Wildcard *	is expanded to all matching directories. Exam-
	      ple: "lib/*/ebin".

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

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

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

	      Option {var_tar,VarTar} can be used to specify if	 and  where  a
	      separate	package	 is to be stored. In this option VarTar	is one
	      of the following:

		include:
		  Each separate	(variable) package is included in the main Re-
		  leaseName.tar.gz file. This is the default.

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

		omit:
		  No separate (variable) packages are generated.  Applications
		  that are found underneath a variable directory are ignored.

	      A	 directory  releases  is also included in the release package,
	      containing Name.rel and a	subdirectory RelVsn. RelVsn is the re-
	      lease 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  or
	      sys.config.src.  These files are searched	for in the same	direc-
	      tory as Name.rel,	in the current working directory, and  in  any
	      directories specified using option path. In the case of sys.con-
	      fig it is	not included if	sys.config.src is found.

	      If the release package is	to 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 with function make_script are	performed  before  the
	      release package is created. Options src_tests and	exref are also
	      valid here.

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

       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.boot file.

	      A	boot script generated using make_script	is already 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	3.3			   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.2-RELEASE+and+Ports>

home | help