User's Guide
Reference Manual
Release Notes
PDF
Top

Reltool
User's Guide
Version 0.5.5

Expand All
Contract All

Chapters

- Introduction
  - Top of chapter
  - Scope and Purpose
  - Prerequisites
  - About This Manual
  - Where to Find More Information
- Usage
  - Top of chapter
  - Overview
  - System window
  - Application window
  - Module window
- Examples
  - Top of chapter
  - Start and stop windows and servers
  - Inspecting the configuration
  - Generate release and script files
  - Create a target system

# 3 Examples

### 3.1 Start and stop windows and servers

The main process in Reltool is the server. It can be used as it is or be used via the GUI frontend process. When the GUI is started, a server process will automatically be started. The GUI process is started with reltool:start/0, reltool:start/1 or reltool:start_link/1. The pid of its server can be obtained with reltool:get_server/1

    Erlang R13B02 (erts-5.7.3) [source] [64-bit] [smp:4:4] [rq:4]
                               [async-threads:0] [kernel-poll:false]

    Eshell V5.7.3  (abort with ^G)
    1> {ok, Win} = reltool:start([]).
    {ok,<0.36.01>}
    2> {ok, Server} = reltool:get_server([]).
    {ok,<0.37.01>}
    3> reltool:get_config(Server).
    {ok,{sys,[]}}
    4> reltool:stop(Win).
    ok

    5> {ok, Server2} = reltool:start_server([]).
    {ok,<0.6535.01>}
    6> reltool:get_config(Server2).
    {ok,{sys,[]}}
    7> reltool:stop(Server2).
    ok

### 3.2 Inspecting the configuration

    Erlang R13B02 (erts-5.7.3) [source] [64-bit] [smp:4:4] [rq:4]
                               [async-threads:0] [kernel-poll:false]

    Eshell V5.7.3  (abort with ^G)
    1> Config = {sys, [{escript,
                        "examples/display_args",
                        [{incl_cond, include}]},
    		   {app, inets, [{incl_cond, include}]},
    		   {app, mnesia, [{incl_cond, exclude}]},
    		   {app, ssl, [{incl_cond, exclude}]},
    		   {app, runtime_tools, [{incl_cond, exclude}]},
    		   {app, syntax_tools, [{incl_cond, exclude}]}]}.
    {sys,[{escript,"examples/display_args",[{incl_cond,include}]},
          {app,inets,[{incl_cond,include}]},
          {app,mnesia,[{incl_cond,exclude}]},
          {app,ssl,[{incl_cond,exclude}]},
          {app,runtime_tools,[{incl_cond,exclude}]},
          {app,syntax_tools,[{incl_cond,exclude}]}]}

    2> {ok, Server} = reltool:start_server([Config]).
    {ok,<0.35.0>}
    3> reltool:get_config(Server).
    {ok,{sys,[{escript,"/clearcase/otp/tools/reltool/examples/display_args",
                       [{incl_cond,include}]}]}}
    4> reltool:get_config(Server, false, false).
    {ok,{sys,[{escript,"/clearcase/otp/tools/reltool/examples/display_args",
                       [{incl_cond,include}]}]}}

    5> reltool:get_config(Server, true, false).
    {ok,{sys,[{root_dir,"/ldisk/hakan/otp_test"},
              {lib_dirs,[]},
              {escript,"/clearcase/otp/tools/reltool/examples/display_args",
                       [{incl_cond,include}]},
              {mod_cond,all},
              {incl_cond,derived},
              {boot_rel,"start_clean"},
              {emu_name,"beam"},
              {relocatable,true},
              {profile,development},
              {incl_sys_files,[".*"]},
              {excl_sys_files,[]},
              {incl_app_files,[".*"]},
              {excl_app_files,[]},
              {incl_archive_dirs,[".*"]},
              {excl_archive_dirs,["^include$","^priv$"]},
              {archive_opts,[]},
              {app_type,permanent},
              {app_file,keep},
              {debug_info,keep}]}}

    6> reltool:get_config(Server, true, true).
    {ok,{sys,[{root_dir,"/ldisk/hakan/otp_test"},
              {lib_dirs,[]},
              {escript,"/clearcase/otp/tools/reltool/examples/display_args",
                       [{incl_cond,include}]},
              {mod_cond,all},
              {incl_cond,derived},
              {erts,[{vsn,"5.7.3"},
                     {mod,erl_prim_loader,[]},
                     {mod,erlang,[]},
                     {mod,init,[]},
                     {mod,otp_ring0,[]},
                     {mod,prim_file,[]},
                     {mod,prim_inet,[]},
                     {mod,prim_zip,[]},
                     {mod,zlib,[]}]},
              {app,compiler,
                   [{vsn,"4.6.3"},
                    {mod,beam_asm,[]},
                    {mod,beam_block,[]},
                    {mod,beam_bool,[]},
                    {mod,beam_bsm,[]},
                    {mod,beam_clean,[]},
                    {mod,beam_dead,[]},
                    {mod,beam_dict,[]},
                    {mod,beam_disasm,[]},
                    {mod,beam_flatten,[]},
                    {mod,beam_jump,[]},
                    {mod,beam_listing,[]},
                    {mod,beam_opcodes,...},
                    {mod,...},
                    {...}|...]},
              {app,crypto,
                   [{vsn,"1.6.1"},
                    {mod,crypto,[]},
                    {mod,crypto_app,[]},
                    {mod,crypto_server,[]},
                    {mod,crypto_sup,[]}]},
              {app,hipe,
                   [{vsn,"3.7.3"},
                    {mod,cerl_cconv,[]},
                    {mod,cerl_closurean,[]},
                    {mod,cerl_hipeify,[]},
                    {mod,cerl_hybrid_transform,[]},
                    {mod,cerl_lib,[]},
                    {mod,cerl_messagean,[]},
                    {mod,cerl_pmatch,[]},
                    {mod,cerl_prettypr,[]},
                    {mod,cerl_to_icode,[]},
                    {mod,cerl_typean,...},
                    {mod,...},
                    {...}|...]},
              {app,kernel,
                   [{vsn,"2.13.3"},
                    {mod,application,[]},
                    {mod,application_controller,[]},
                    {mod,application_master,[]},
                    {mod,application_starter,[]},
                    {mod,auth,[]},
                    {mod,code,[]},
                    {mod,code_server,[]},
                    {mod,disk_log,[]},
                    {mod,disk_log_1,...},
                    {mod,...},
                    {...}|...]},
              {app,stdlib,
                   [{vsn,"1.16.3"},
                    {mod,array,[]},
                    {mod,base64,[]},
                    {mod,beam_lib,[]},
                    {mod,c,[]},
                    {mod,calendar,[]},
                    {mod,dets,[]},
                    {mod,dets_server,[]},
                    {mod,dets_sup,...},
                    {mod,...},
                    {...}|...]},
              {boot_rel,"start_clean"},
              {emu_name,"beam"},
              {relocatable,true},
              {profile,development},
              {incl_sys_files,[".*"]},
              {excl_sys_files,[]},
              {incl_app_files,[".*"]},
              {excl_app_files,[]},
              {incl_archive_dirs,[".*"]},
              {excl_archive_dirs,["^include$",[...]]},
              {archive_opts,[]},
              {app_type,permanent},
              {app_file,...},
              {...}]}}

    7> reltool:get_config([{sys,[{profile, embedded}]}]).
    {ok,{sys,[{profile,embedded},
              {incl_sys_filters,["^bin","^erts","^lib","^releases"]},
              {excl_sys_filters,["^bin/(erlc|dialyzer|typer)(|\\.exe)$",
                                 "^erts.*/bin/(erlc|dialyzer|typer)(|\\.exe)$",
                                 "^erts.*/bin/.*(debug|pdb)"]},
              {incl_app_filters,["^ebin","^include","^priv"]}]}}
    8> reltool:get_config([{sys,[{profile, standalone}]}]).
    {ok,{sys,[{profile,standalone},
              {incl_sys_filters,["^bin/(erl|epmd)(|\\.exe|\\.ini)$",
                                 "^bin/start(|_clean).boot$","^erts.*/bin","^lib$"]},
              {excl_sys_filters,["^erts.*/bin/(erlc|dialyzer|typer)(|\\.exe)$",
                                 "^erts.*/bin/(start|escript|to_erl|run_erl)(|\\.exe)$",
                                 "^erts.*/bin/.*(debug|pdb)"]},
              {incl_app_filters,["^ebin","^priv"]},
              {excl_app_filters,["^ebin/.*\\.appup$"]}]}}

### 3.3 Generate release and script files

    5> {ok, Server} = reltool:start_server([{config, {sys, [{boot_rel, "NAME"},
                                                            {rel, "NAME", "VSN",
                                                            [sasl]}]}}]).
    {ok,<0.1288.0>}
    6>  reltool:get_config(Server).
    {ok,{sys,[{boot_rel,"NAME"},
              {rel,"NAME","VSN",[sasl]}]}}
    7>  reltool:get_rel(Server, "NAME").
    {ok,{release,{"NAME","VSN"},
                 {erts,"5.7"},
                 [{kernel,"2.13"},{stdlib,"1.16"},{sasl,"2.1.6"}]}}
    8>  reltool:get_script(Server, "NAME").
    {ok,{script,{"NAME","VSN"},
                [{preLoaded,[erl_prim_loader,erlang,init,otp_ring0,
                             prim_file,prim_inet,prim_zip,zlib]},
                 {progress,preloaded},
                 {path,["$ROOT/lib/kernel-2.13/ebin",
                        "$ROOT/lib/stdlib-1.16/ebin"]},
                 {primLoad,[error_handler]},
                 {kernel_load_completed},
                 {progress,kernel_load_completed},
                 {path,["$ROOT/lib/kernel-2.13/ebin"]},
                 {primLoad,[application,application_controller,
                            application_master,application_starter,auth,code,
                            code_server,disk_log,disk_log_1,disk_log_server,
                            disk_log_sup,dist_ac,dist_util,erl_boot_server|...]},
                 {path,["$ROOT/lib/stdlib-1.16/ebin"]},
                 {primLoad,[array,base64,beam_lib,c,calendar,dets,
                            dets_server,dets_sup,dets_utils,dets_v8,dets_v9,dict|...]},
                 {path,["$ROOT/lib/sasl-2.1.6/ebin"]},
                 {primLoad,[alarm_handler,erlsrv,format_lib_supp,misc_supp,
                            overload,rb,rb_format_supp,release_handler,
                            release_handler_1,sasl|...]},
                 {progress,modules_loaded},
                 {path,["$ROOT/lib/kernel-2.13/ebin",
                        "$ROOT/lib/stdlib-1.16/ebin","$ROOT/lib/sasl-2.1.6/ebin"]},
                 {kernelProcess,heart,{heart,start,[]}},
                 {kernelProcess,error_logger,{error_logger,start_link,[]}},
                 {kernelProcess,application_controller,
                                {application_controller,start,[{...}]}},
                 {progress,init_kernel_started},
                 {apply,{application,load,[...]}},
                 {apply,{application,load,...}},
                 {progress,applications_loaded},
                 {apply,{...}},
                 {apply,...},
                 {...}|...]}}
    9>  reltool:stop(Server).
    ok

### 3.4 Create a target system

    Erlang R13B02 (erts-5.7.3) [source] [64-bit] [smp:4:4] [rq:4]
                               [async-threads:0] [kernel-poll:false]

    Eshell V5.7.3  (abort with ^G)
    1> Config = {sys, [{escript,
                        "examples/display_args",
                        [{incl_cond, include}]},
    		   {app, inets, [{incl_cond, include}]},
    		   {app, mnesia, [{incl_cond, exclude}]},
    		   {app, ssl, [{incl_cond, exclude}]},
    		   {app, runtime_tools, [{incl_cond, exclude}]},
    		   {app, syntax_tools, [{incl_cond, exclude}]}]}.
    {sys,[{escript,"examples/display_args",[{incl_cond,include}]},
          {app,inets,[{incl_cond,include}]},
          {app,mnesia,[{incl_cond,exclude}]},
          {app,ssl,[{incl_cond,exclude}]},
          {app,runtime_tools,[{incl_cond,exclude}]},
          {app,syntax_tools,[{incl_cond,exclude}]}]}

    2> {ok, Spec} = reltool:get_target_spec([Config]).
    {ok,[{create_dir,"releases",
                     [{write_file,"start_erl.data","5.7.3 1.0"},
                      {create_dir,"1.0",
                                  [{write_file,"start_clean.rel",
                                               [37,37,32,114,101,108,32,103,101,110,101|...]},
                                   {write_file,"start_clean.script",
                                               [37,37,32,115,99,114,105,112,116,32|...]},
                                   {write_file,"start_clean.boot",
                                               <<131,104,3,100,0,6,115,99,114,...>>},
                                   {write_file,"start_sasl.rel",
                                               [37,37,32,114,101,108,32,103,101,110,101|...]},
                                   {write_file,"start_sasl.script",
                                               [37,37,32,115,99,114,105,112,116,32|...]},
                                   {write_file,"start_sasl.boot",
                                               <<131,104,3,100,0,6,115,99,114,...>>}]}]},
         {create_dir,"bin",
                     [{copy_file,"display_args.escript",
                                 "/clearcase/otp/tools/reltool/examples/display_args"},
                      {copy_file,"display_args","erts-5.7.3/bin/escript"},
                      {copy_file,"start","erts-5.7.3/bin/start"},
                      {copy_file,"erl","erts-5.7.3/bin/dyn_erl"},
                      {copy_file,"epmd","erts-5.7.3/bin/epmd"},
                      {copy_file,"to_erl","erts-5.7.3/bin/to_erl"},
                      {copy_file,"run_erl","erts-5.7.3/bin/run_erl"},
                      {copy_file,"escript","erts-5.7.3/bin/escript"},
                      {copy_file,"erlc","erts-5.7.3/bin/erlc"},
                      {copy_file,"dialyzer","erts-5.7.3/bin/dialyzer"},
                      {copy_file,"typer","erts-5.7.3/bin/typer"},
                      {write_file,"start_clean.boot",
                                  <<131,104,3,100,0,6,115,...>>},
                      {write_file,"start_sasl.boot",<<131,104,3,100,0,6,...>>},
                      {write_file,"start.boot",<<131,104,3,100,0,...>>}]},
         {create_dir,"misc",
                     [{copy_file,"makewhatis"},{copy_file,"format_man_pages"}]},
         {copy_file,"Install"},
         {create_dir,"usr",
                     [{create_dir,"lib",
                                  [{copy_file,"liberts_r.a"},{copy_file,"liberts.a"}]},
                      {create_dir,"include",
                                  [{copy_file,"erl_fixed_size_int_types.h"},
                                   {copy_file,"erl_int_sizes_config.h"},
                                   {copy_file,"erl_memory_trace_parser.h"},
                                   {create_dir,"obsolete",[{copy_file,"driver.h"}]},
                                   {copy_file,"driver_int.h"},
                                   {copy_file,"erl_driver.h"}]}]},
         {create_dir,"erts-5.7.3",
                     [{create_dir,"lib",
                                  [{create_dir,"internal",
                                               [{copy_file,"liberts_internal_r.a"},
                                                {copy_file,"liberts_internal.a"},
                                                {copy_file,"libethread.a"},
                                                {copy_file,"README"}]},
                                   {copy_file,"liberts_r.a"},
                                   {copy_file,"liberts.a"}]},
                      {create_dir,"bin",
                                  [{copy_file,"start"},
                                   {copy_file,"erl","erts-5.7.3/bin/dyn_erl"},
                                   {copy_file,"epmd"},
                                   {copy_file,"to_erl"},
                                   {copy_file,"run_erl"},
                                   {copy_file,"escript"},
                                   {copy_file,"erlc"},
                                   {copy_file,"dialyzer"},
                                   {copy_file,"typer"},
                                   {copy_file,"erlexec"},
                                   {copy_file,[...]},
                                   {copy_file,...},
                                   {...}|...]},
                      {create_dir,"doc",[]},
                      {create_dir,"man",[]},
                      {create_dir,"include",
                                  [{create_dir,"internal",
                                               [{create_dir,"tile",[{copy_file,...},{...}]},
                                                {create_dir,"sparc64",[{...}]},
                                                {create_dir,"sparc32",[...]},
                                                {create_dir,[...],...},
                                                {create_dir,...},
                                                {...}|...]},
                                   {copy_file,"erl_fixed_size_int_types.h"},
                                   {copy_file,"erl_int_sizes_config.h"},
                                   {copy_file,"erl_memory_trace_parser.h"},
                                   {copy_file,"driver_int.h"},
                                   {copy_file,"erl_driver.h"}]},
                      {create_dir,"src",[{copy_file,"setuid_socket_wrap.c"}]}]},
         {create_dir,"lib",
                     [{archive,"compiler-4.6.3.ez",[],
                               [{create_dir,"compiler-4.6.3",
                                            [{create_dir,"ebin",
                                                         [{copy_file,"compiler.appup"},
                                                          {copy_file,[...]},
                                                          {copy_file,...},
                                                          {...}|...]},
                                             {create_dir,"src",
                                                         [{copy_file,[...]},
                                                          {copy_file,...},{...}|...]}]}]},
                      {archive,"crypto-1.6.1.ez",[],
                               [{create_dir,"crypto-1.6.1",
                                            [{create_dir,"ebin",
                                                         [{copy_file,[...]},
                                                          {copy_file,...},{...}|...]},
                                             {create_dir,"src",[{copy_file,...},{...}|...]}]}]},
                      {create_dir,"crypto-1.6.1",
                                  [{create_dir,"priv",
                                               [{create_dir,"lib",[{copy_file,[...]}]},
                                                {create_dir,"obj",[{copy_file,...},{...}]}]}]},
                      {archive,"erts-5.7.3.ez",[],
                               [{create_dir,"erts-5.7.3",
                                            [{create_dir,"ebin",[{...}|...]},
                                             {create_dir,"src",[...]}]}]},
                      {archive,"hipe-3.7.3.ez",[],
                               [{create_dir,"hipe-3.7.3",
                                            [{create_dir,"util",[...]},
                                             {create_dir,[...],...},
                                             {create_dir,...},
                                             {...}|...]}]},
                      {archive,"kernel-2.13.3.ez",[],
                               [{create_dir,"kernel-2.13.3",
                                            [{create_dir,[...],...},{create_dir,...},{...}]}]},
                      {create_dir,"kernel-2.13.3",
                                  [{create_dir,"include",
                                               [{copy_file,[...]},{copy_file,...},{...}]}]},
                      {archive,"stdlib-1.16.3.ez",[],
                               [{create_dir,"stdlib-1.16.3",[{...}|...]}]},
                      {create_dir,"stdlib-1.16.3",
                                  [{create_dir,"include",[{...}|...]}]}]}]}

    3> TargetDir = "my_target_dir".
    "my_target_dir"
    4> reltool:eval_target_spec(Spec, code:root_dir(), TargetDir).
    {error,"/clearcase/otp/tools/reltool/my_target_dir: no such file or directory"}
    5> file:make_dir("my_target_dir").
    ok
    6> reltool:eval_target_spec(Spec, code:root_dir(), TargetDir).
    ok
    7> file:list_dir(TargetDir).
    {ok,["lib","erts-5.7.3","usr","Install","misc","bin","releases"]}
    8> file:list_dir(filename:join([TargetDir,"lib"])).
    {ok,["stdlib-1.16.3","stdlib-1.16.3.ez","kernel-2.13.3",
         "kernel-2.13.3.ez","hipe-3.7.3.ez","erts-5.7.3.ez",
         "crypto-1.6.1","crypto-1.6.1.ez","compiler-4.6.3.ez"]}
    9> file:make_dir("yet_another_target_dir").
    ok
    10> reltool:create_target(Config, "yet_another_target_dir").
    ok