Module ammcore.bootloader

Bootloader implements the require() function and all necessary APIs for it to function.

global require(modname: string) → unknown, loaderdata: unknown

Load the given module, run it, and forward any returned value.

If module returns nil, it is replaced with true.

Besides that value, require() also returns as a second result the loader data returned by the searcher, which indicates how require() found the module. For instance, if the module came from a file, this loader data is the file path.

Index

Function

findModuleCode()	Find and return a file by its path.
getBootloaderConfig()	Get bootloader config.
getDevRoot()	Get directory for dev packages if one is configured.
getFile()	Get file name at stack frame n.
getLine()	Get current line number at stack frame n.
getLoaderKind()	Get name of the loader that was used to load the code.
getLoc()	Get current location at stack frame n.
getMod()	Get module name at stack frame n.
getModuleByRealPath()	Given a real file path (as returned by findModuleCode), look up associated module name.
getSrvRoot()	Get directory for internal AMM files.
main()	Initialize and install the global require function, then start a user script configured via computer's nick or config.prog.

Class

BootloaderConfig

A bootloader config.

Function

ammcore.bootloader.findModuleCode(path: string | string[]) → code?: string, realPath?: string

Find and return a file by its path.

If given an array of strings, then the first found file is returned. For example, findModuleCode({ "a/b/_index.lua", "a/b.lua" }) will try "a/b/_index.lua" first, then "a/b.lua". It will return contents of the first file that exists.

Note: code is not cached. If target loader is ‘net’, this call will issue a request to a code server. If target loader is ‘drive’ and the code has changed since it was last loaded, this function will return the new version of the code.

Parameters:

path (string | string[]) – file path, including its extension.

Returns:

• code? (string) – module code.

• realPath? (string) – actual path to the lua file that contains the code.

ammcore.bootloader.getBootloaderConfig() → config: ammcore.bootloader.BootloaderConfig | {[string]: unknown}

Get bootloader config.

Returns:

config (ammcore.bootloader.BootloaderConfig | {[string]: unknown}) – config that was used to init the bootloader.

ammcore.bootloader.getDevRoot() → devRoot: string

Get directory for dev packages if one is configured.

Return nil if bootloader target is not drive.

Returns:

devRoot (string) – directory where dev packages are installed.

ammcore.bootloader.getFile(n?: integer) → file: string

Get file name at stack frame n.

Parameters:

n? (integer) – number of stack frame from the top of the stack. By default, return file of the calling frame.

Returns:

file (string) – file name.

ammcore.bootloader.getLine(n?: integer) → line: integer

Get current line number at stack frame n.

Parameters:

n? (integer) – number of stack frame from the top of the stack. By default, return line at the calling frame.

Returns:

line (integer) – line number.

ammcore.bootloader.getLoaderKind() → "drive" | "net"

Get name of the loader that was used to load the code.

ammcore.bootloader.getLoc(n?: integer) → location: string

Get current location at stack frame n.

Parameters:

n? (integer) – number of stack frame from the top of the stack. By default, return location of the calling frame.

Returns:

location (string) – location, consists of file name and line number.

ammcore.bootloader.getMod(n?: integer) → module: string

Get module name at stack frame n.

Parameters:

n? (integer) – number of stack frame from the top of the stack. By default, return module of the calling frame.

Returns:

module (string) – module name.

ammcore.bootloader.getModuleByRealPath(realPath: string) → string?

Given a real file path (as returned by findModuleCode()), look up associated module name.

Parameters:

realPath (string) – real path to a file, as returned by findModuleCode() or ammcore._util.debug.getFile.

ammcore.bootloader.getSrvRoot() → srvRoot: string

Get directory for internal AMM files.

Return nil if bootloader target is not drive.

Returns:

srvRoot (string) – directory where AMM stores its internal data, including installed modules.

ammcore.bootloader.main(config: ammcore.bootloader.BootloaderConfig | {[string]: unknown}, coreCodeLocation: string | table<string, string>)

Initialize and install the global require() function, then start a user script configured via computer’s nick or config.prog.

Parameters:

• config (ammcore.bootloader.BootloaderConfig | {[string]: unknown}) – bootloader config.

• coreCodeLocation (string | table<string, string>) – code table from the bootstrap script.

Class

class ammcore.bootloader.BootloaderConfig : {[string]: unknown}

A bootloader config.

prog: string?

Which program to run after the system is fully booted. This can be any Lua package installed on your AMM code server.

Some standard programs include:

• “.help” – print this message and stop the computer;

• “.eeprom” – do nothing and continue executing EEPROM;

On code server, these are also available:

• “.provision” – install “ammcore” locally and replace EEPROM with a default one. This will be the first program that you run on a new computer.

• “.server” – start code server;

• “.lspkg” – list all locally installed packages;

• “.check” – check integrity of installed packages;

• “.install” – install packages from config.packages;

• “.upgrade” – upgrade all packages to the latest version;

• “ammtest.bin.main” – run unit tests on local dev packages.

If “prog” is not specified in the config, it is parsed from computer’s nick. If computer’s nick is empty, “.eeprom” is implied.

Note

Starting program name with a dot is a shortcut for “ammcore.bin.<program>”.

target: "drive" | "net"

Where to find installed AMM packages. Available values are:

• “drive” will load AMM code from this computer’s hard drive.

• “net” will fetch AMM code from another computer (a code server) using NetBoot protocol.

Target is configured by EEPROM depending on specific computer’s purpose. It is required to initialize the bootloader.

devRoot: string

Only meaningful on code server. Directory with user code (a.k.a. dev packages). Default is “/”.

Dev root is always configured by EEPROM. It is required to initialize the bootloader.

Directory for dev packages if one is configured, used when target is drive.

srvRoot: string

Directory with internal AMM files. Default is “/.amm”.

Srv root is always configured by EEPROM. It is required to initialize the bootloader.

driveId: string?

Id of a hard drive with AMM files.

This setting is used by EEPROM to mount a hard drive and locate the bootstrap script. However, it might not be set if user implemented a custom EEPROM version.

mountPoint: string?

Directory where hard drive will be mounted. Default is “/”.

This setting is used by EEPROM to mount a hard drive and locate the bootstrap script. However, it might not be set if user implemented a custom EEPROM version.

bootAddr: string?

Address of the code server, used when tartet is “net”.

By default it is discovered through a broadcast request.

Address of the code server, used when target is net.

bootPort: integer?

Port of the code server, used when tartet is “net”. Default is “0x1CD”.

Port of the code server, used when target is net.

packages: string[]?

Only meaningful on code server. This setting lists all packages that should be installed.

logLevels: table<string, ammcore.log.Level>

Configuration for loggers.

configuration for loggers.