====== External Program Installer ======


This script parses a ''.ini'' file (default filename is ''install-xtrn.ini'') and installs the external programs defined within into the Synchronet BBS configuration file: ''[[dir:ctrl]]/xtrn.ini''((xtrn.cnf in older versions of Synchronet)). The programs defined within this file can by online programs (a.k.a. Doors), message editors, or timed events.

This script can by invoked in a more user-friendly automated fashion by running [[person:echicken]]'s [[module:xtrn-setup]] module instead.

If the door is included with Synchronet, or Synchronet already has a configuration for it (in ''xtrn/3rdp-install''), you can use the ''install-xtrn.js'' script to install your door. For third party doors, you should extract the door files into your external directory first, and perform any required unpacking/installing of the files. Once the final executable file is in place, Synchronet can check for a file signature match and install the door configuration if it has a matching known configuration for it. 

===== Running the Script ====

Run ''[[dir:exec]]/jsexec install-xtrn.js''

This script can also be invoked using the ;EXEC sysop command while logged into the terminal server, for example:

'';exec ?install-xtrn''

You can also specify a specific directory to install by including the path to the program:

''[[dir:exec]]/jsexec install-xtrn.js ../xtrn/minesweeper''

'';exec ?install-xtrn ../xtrn/minesweeper''

===== Command Line Options =====

^ Command ^ Description ^
| -auto | Don't prompt for a list of doors to install |
| -debug | Shows what would happen (does not make changes) |
| -overwrite | Overwrite already-installed door |

===== Third Party External Programs (Doors) =====

Configurations are located in ''[[dir:xtrn]]/3rdp-install'' to support the installing popular third party doors. These configurations are version-specific and are based on a MD5 hash of the door's primary executable file.

The general instructions are:

  - Download the file from the program author's website
  - Extract the file into the destination directory of your xtrn folder
  - Inside that directory, do any actions you need to get the files into their final state. For example, extracting any included zip files, running any uncompressors or installer programs, installing any patches (like ''tppatch'' for Turbo Basic programs), etc.
  - Review the sysop documentation for the program
  - Run the ''install-xtrn.js''. If it finds a match (based on a MD5 sum of the executable), it will give you the option to install the program and decide which external section to place it into. If it does not give you the option, then either no configuration exists in ''[[dir:xtrn]]/3rdp-install'' for this program or this particular version of the program, or you may have missed a step preparing the files
  - Perform any required tasks according to the sysop documentation, such as resetting the program, etc.
  - Apply any registration codes you have for the program

===== install_xtrn.ini =====

 This script is intended for use by sysops using JSexec, for example:
   $ jsexec install-xtrn ../xtrn/minesweeper

 This script can aso be invoked using the ;EXEC sysop command while logged
 into the terminal server, for example:
   ;exec ?install-xtrn ../xtrn/minesweeper

 ''install-xtrn.js'' reads the directory specified  install-xtrn.ini (e.g.: ../xtrn/minesweeper/install-xtrn.ini)

 The .ini root section keys supported:

 Name = Name of the program being installed (79 chars or less)\\
 Desc = Description of the program being installed (79 chars or less)\\
 By   = Comma-separated list of programmers/authors/publishers\\
 Cats = Comma-separated list of applicable categories (e.g. "Games")\\
 Subs = Comma-separated list of applicable sub-categories (e.g. "Adventure")\\
 Inst = Installer .ini file source/revision/author/date information\\

 The .ini sections and keys supported (zero or more of each may be included):

 [pre-exec:<file>.js [args]] ; execute file.js before installing programs
		startup_dir		= directory to make current before execution

 [pre-eval:<js-expression>] ; evaluate js-expression before installing progs
      cmd             = evaluate this string rather than the js-expression

 [prog:<code>]
 		name 			= program name or description (40 chars max)
      	cats            = additional target installation categories (sections)
		cmd 			= command-line to execute (63 chars max)
		clean_cmd 		= clean-up command-line, if needed (63 chars max)
		settings 		= bit-flags (see XTRN_* in sbbsdefs.js)
		ars				= access requirements string (40 chars max)
		execution_ars	= execution requirements string (40 chars max)
		type			= drop-file type (see XTRN_* in sbbsdefs.js)
		event			= event-type (see EVENT_* in sbbsdefs.j)
		cost			= cost to run, in credits
		startup_dir		= directory to make current before execution
		textra			= extra time (minutes) to allow to run this program
		max_time		= maximum time (minutes) allowed to run this program

 [event:<code>]
		cmd 			= command-line to execute (63 chars max)
		days			= bit-field representing days of the week to execute
		time			= time of day to run this event
		node_num		= node number to run this event
		settings		= bit-flags (see XTRN_* in sbbsdefs.js)
		startup_dir		= directory to make current before execution
		freq			= frequency of execution
		mdays			= days of month (if non-zero) for execution
		months			= bit-field representing which months to execute

 [editor:<code>]
		name 			= editor name or description (40 chars max)
		cmd 			= command-line to execute (63 chars max)
		type			= drop-file type (see XTRN_* in sbbsdefs.js)
		settings 		= bit-flags (see XTRN_* in sbbsdefs.js)
		ars				= access requirements string (40 chars max)

 [service:<protocol>]
      see ctrl/services.ini 

 [exec:<file>.js [args]] ; execute file.js with these arguments - after
		startup_dir		= directory to make current before execution

 [eval:<js-expression>] ; evaluate js-expression after installing programs
      cmd             = evaluate this string rather than the js-expression

 [ini:<filename.ini>[:section]]
      keys            = comma-separated list of keys to add/update in .ini
      values          = list of values to eval() and assign to keys[]
                        Note: string values must be enclosed in quotes!

 Additionally, each section can have the following optional keys that are
 only used by this script (i.e. not written to any configuration files):
		note			= note to sysop displayed before installation
		fail			= note to sysop displayed upon failure
      	prompt          = confirmation prompt (or false if no prompting)
		required		= if true, this item must be successful to continue
      	last            = if true, this item will be the last of its type
      	done            = if true, no more installer items will be processed

 Notes:

 - The startup_dir will default to the location of the .ini file if this
   key is not defined within the .ini file.

 - The only required values are the <code> (internal code, 8 chars max) and
   cmd; all other keys will have functional default values if not defined in
   the .ini file.

 ===== Example install-xtrn.ini =====
  
  Name: AlleyCat! BBS Game Server Games
  Desc: Available Programs for use with acgs rgate.js connector
  By:   mortifis @ alleycat bbs
  Cats: Games
  Subs: GAMES, SBBS DEMOS
  Inst: 2021/01/02
  
  [prog:V200G]
  name =Synchronet         2.00g
  startup_dir = 
  cmd=?rgate.js v200g
  execution_ars  = 
  settings = XTRN_ANSI | XTRN_SH | XTRN_MULTIUSER
  type = 
  
  [prog:V230C]
  name =Synchronet         2.30c
  startup_dir =
  cmd=?rgate.js v230c
  execution_ars  = 
  settings = XTRN_ANSI | XTRN_SH | XTRN_MULTIUSER
  type = 
  
  [prog:SBBS1A14]
  name =Synchronet         1a14
  startup_dir =
  cmd=?rgate.js sbbs1a14
  execution_ars  = 
  settings = XTRN_ANSI | XTRN_SH | XTRN_MULTIUSER
  type = 
  
  [prog:TW2G2]
  name = TW2002 Gergovia
  cmd = ?rgate.js tw2g2
  execution_ars  = NOT GUEST
  settings = XTRN_ANSI | XTRN_SH | XTRN_MULTIUSER
  type = XTRN_GAP

  [prog:TW2G3]
  name = TW2002 Hoboistica
  cmd = ?rgate.js tw2g3
  execution_ars  = NOT GUEST
  settings = XTRN_ANSI | XTRN_SH | XTRN_MULTIUSER
  type = XTRN_GAP


===== See Also =====
  * [[:util:index:|Utilities]]
  * [[:howto:door:index |Install Doors]]
{{tag>jsutil}}
