👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for systools (linux section 3erl)

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 {out-
	      dir,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 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. Instruc-
	      tions for upgrading or downgrading between application 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  trans-
	      lated 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 directories. 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  applica-
		  tions 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 wildcard * , 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 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 directory 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 appli-
	      cation will get the path VarName/Rest/App-Vsn/ebin in the boot script. If an appli-
	      cation  is  found  in  a directory Prefix/Rest , the path will be VarName/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 unde-
	      fined 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,Mod-
	      ule,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  |  {out-
		     dir,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  applica-
	      tion 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 Release-
		  Name.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 speci-
	      fied 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 direc-
	      tory 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)


All times are GMT -4. The time now is 03:01 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password





Not a Forum Member?
Forgot Password?