chdir($CFG::builddir) or die "Can't change directory to $CFG::builddir: $!";
print "novaboot: Entering directory `$CFG::builddir'\n";
-## Process novaboot scripts
+## File generation phase
my (%files_iso, $menu_iso, $config_name, $filename);
foreach my $script (@scripts) {
=back
-=head1 OPTIONS
+=head1 PHASES AND OPTIONS
+
+Novaboot perform its work in several phases. Each phase can be
+influenced by several options, certain phases can be skipped. The list
+of phases with the corresponding options follows.
+
+=head2 Command line processing phase
=over 8
-=item -a, --append=<parameters>
+=item -c, --config=<filename>
-Appends a string to the root task's command line.
+Use a different configuration file than the default one (i.e.
+F<~/.novaboot>).
-=item -b, --bender
+=item --dump-config
-Boot bender tool before the kernel to find PCI serial ports.
+Dumps current configuration to stdout end exits. Useful as an initial
+template for a configuration file.
-=item --build-dir=<directory>
+=item -h, --help
-Overrides the default build directory location.
+Print short (B<-h>) or long (B<--help>) help.
-The default build directory location is determined as follows:
+=item -I
-If there is a configuration file, the value specified in I<$builddir>
-variable is used. Otherwise, if the current working directory is
-inside git work tree and there is F<build> directory at the top of
-that tree, it is used. Otherwise, if directory F<~/nul/build> exists,
-it is used. Otherwise, it is the directory that contains the first
-processed novaboot script.
+This is an alias (see C<%custom_options> below) defined in the default
+configuration. When used, it causes novaboot to use Michal's remotely
+controllable test bed.
-=item -c, --config=<filename>
+=item -J
-Use a different configuration file than the default one (i.e.
-F<~/.novaboot>).
+This is an alias (see C<%custom_options> below) defined in the default
+configuration. When used, it causes novaboot to use another remotely
+controllable test bed.
-=item -d, --dhcp-tftp
+=back
-Turns your workstation into a DHCP and TFTP server so that NOVA
-can be booted via PXE BIOS on a test machine directly connected by
-a plain Ethernet cable to your workstation.
+=head2 Script preprocessing phase
-The DHCP and TFTP servers require root privileges and C<novaboot>
-uses C<sudo> command to obtain those. You can put the following to
-I</etc/sudoers> to allow running the necessary commands without
-asking for password.
+This phases allows to modify the parsed novaboot script before it is
+used in the later phases.
- Cmnd_Alias NOVABOOT = /bin/ip a add 10.23.23.1/24 dev eth0, /bin/ip l set dev eth0 up, /usr/sbin/dhcpd -d -cf dhcpd.conf -lf dhcpd.leases -pf dhcpd.pid, /usr/sbin/in.tftpd --foreground --secure -v -v -v *, /usr/bin/touch dhcpd.leases
- your_login ALL=NOPASSWD: NOVABOOT
+=over 8
+
+=item -a, --append=<parameters>
+
+Appends a string to the first "filename" line in the novaboot script.
+This can be used to append parameters to the kernel's or root task's
+command line.
+
+=item -b, --bender
+
+Use F<bender> chainloader. Bender scans the PCI bus for PCI serial
+ports and stores the information about them in the BIOS data area for
+use by the kernel.
=item --dump
Prints the content of the novaboot script after removing comments and
-evaluating all I<--scriptmod> expressions.
+evaluating all I<--scriptmod> expressions. Exit after reading (and
+dumping) the script.
-=item --dump-config
+=item --scriptmod=I<perl expression>
-Dumps current configuration to stdout end exits. Useful as an initial
-template for a configuration file.
+When novaboot script is read, I<perl expression> is executed for every
+line (in $_ variable). For example, C<novaboot
+--scriptmod=s/sigma0/omega6/g> replaces every occurrence of I<sigma0>
+in the script with I<omega6>.
+
+When this option is present, it overrides I<$script_modifier> variable
+from the configuration file, which has the same effect. If this option
+is given multiple times all expressions are evaluated in the command
+line order.
+
+=item --strip-rom
+
+Strip I<rom://> prefix from command lines and generated config files.
+The I<rom://> prefix is used by NUL. For NRE, it has to be stripped.
+
+=back
+
+=head2 File generation phase
+
+In this phase, files needed for booting are generated in a so called
+I<build directory> (see TODO). In most cases configuration for a
+bootloader is generated automatically by novaboot. It is also possible
+to generate other files using I<heredoc> or I<"<"> syntax in novaboot
+scripts. Finally, binaries can be generated in this phases by running
+C<scons> or C<make>.
+
+=over 8
+
+=item --build-dir=<directory>
+
+Overrides the default build directory location.
+
+The default build directory location is determined as follows:
+
+If there is a configuration file, the value specified in the
+I<$builddir> variable is used. Otherwise, if the current working
+directory is inside git work tree and there is F<build> directory at
+the top of that tree, it is used. Otherwise, if directory
+F<~/nul/build> exists, it is used. Otherwise, it is the directory that
+contains the first processed novaboot script.
=item -g, --grub[=I<filename>]
-Generates grub menu file. If the I<filename> is not specified,
-F<menu.lst> is used. The I<filename> is relative to NUL build
-directory.
+Generates grub bootloader menu file. If the I<filename> is not
+specified, F<menu.lst> is used. The I<filename> is relative to the
+build directory (see B<--build-dir>).
=item --grub-prefix=I<prefix>
-Specifies I<prefix> that is put before every file in GRUB's menu.lst.
+Specifies I<prefix> that is put before every file in GRUB's F<menu.lst>.
This overrides the value of I<$server_grub_prefix> from the
configuration file.
=item --grub2[=I<filename>]
Generate GRUB2 menuentry in I<filename>. If I<filename> is not
-specified grub.cfg is used. The content of the menuentry can be
+specified F<grub.cfg> is used. The content of the menuentry can be
customized by I<$grub2_prolog> and I<$server_grub_prefix>
configuration variables.
source /path/to/nul/build/grub.cfg
fi
+=item --name=I<string>
-=item -h, --help
+Use the name I<string> instead of the name of the novaboot script.
+This name is used for things like a title of grub menu or for the
+server directory where the boot files are copied to.
-Print short (B<-h>) or long (B<--help>) help.
+=item --no-file-gen
-=item --iprelay[=addr or cmd]
+Do not generate files on the fly (i.e. "<" syntax) except for the
+files generated via "<<WORD" syntax.
-If no I<cmd> is given, use IP relay to reset the machine and to get
-the serial output. The IP address of the relay is given by I<addr>
-parameter if specified or by $iprelay_addr variable in the
-configuration file.
+=item -p, --pulsar[=mac]
-If I<cmd> is one of "on" or "off", the IP relay is used to press power
-button for a short (in case of "on") or long (in case of "off") time.
-Then, novaboot exits.
+Generates pulsar bootloader configuration file whose name is based on
+the MAC address specified either on the command line or taken from
+I<.novaboot> configuration file.
-Note: This option is expected to work with HWG-ER02a IP relays.
+=back
+
+=head2 File deployment phase
+
+In some setups, it is necessary to copy the files needed for booting
+to a particular location, e.g. to a TFTP boot server or to the
+F</boot> partition.
+
+=over 8
+
+=item -d, --dhcp-tftp
+
+Turns your workstation into a DHCP and TFTP server so that NOVA
+can be booted via PXE BIOS on a test machine directly connected by
+a plain Ethernet cable to your workstation.
+
+The DHCP and TFTP servers require root privileges and C<novaboot>
+uses C<sudo> command to obtain those. You can put the following to
+I</etc/sudoers> to allow running the necessary commands without
+asking for password.
+
+ Cmnd_Alias NOVABOOT = /bin/ip a add 10.23.23.1/24 dev eth0, /bin/ip l set dev eth0 up, /usr/sbin/dhcpd -d -cf dhcpd.conf -lf dhcpd.leases -pf dhcpd.pid, /usr/sbin/in.tftpd --foreground --secure -v -v -v *, /usr/bin/touch dhcpd.leases
+ your_login ALL=NOPASSWD: NOVABOOT
=item -i, --iso[=filename]
Generates the ISO image that boots NOVA system via GRUB. If no filename
is given, the image is stored under I<NAME>.iso, where I<NAME> is the name
-of novaboot script (see also B<--name>).
+of the novaboot script (see also B<--name>).
-=item -I
+=item --server[=[[user@]server:]path]
-This is an alias (see C<%custom_options> below) defined in the default
-configuration. When used, it causes novaboot to use Michal's remotely
-controllable test bed.
+Copy all files needed for booting to another location (implies B<-g>
+unless B<--grub2> is given). The files will be copied (by B<rsync>
+tool) to the directory I<path>. If the I<path> contains string $NAME,
+it will be replaced with the name of the novaboot script (see also
+B<--name>).
-=item -J
+Additionally, if $NAME is the last component of the I<path>, a file
+named I<path>/menu.lst (with $NAME removed from the I<path>) will be
+created on the server by concatenating all I<path>/*/menu.lst (with
+$NAME removed from the I<path>) files found on the server.
-This is an alias (see C<%custom_options> below) defined in the default
-configuration. When used, it causes novaboot to use another remotely
-controllable test bed.
+=item --rsync-flags=I<flags>
-=item --on, --off
+Specifies which I<flags> are appended to F<rsync> command line when
+copying files as a result of I<--server> option.
-Synonym for --iprelay=on/off.
+=item --scons[=scons command]
-=item --name=I<string>
+Runs I<scons> to build files that are not generated by novaboot
+itself.
-Use the name I<string> instead of the name of the novaboot script.
-This name is used for things like a title of grub menu or for the
-server directory where the boot files are copied to.
+=back
-=item --no-file-gen
+=head2 Target power-on and reset phase
-Do not generate files on the fly (i.e. "<" syntax) except for the
-files generated via "<<WORD" syntax.
+=over 8
-=item -p, --pulsar[=mac]
+=item --iprelay[=addr or cmd]
-Generates pulsar bootloader configuration file whose name is based on
-the MAC address specified either on the command line or taken from
-I<.novaboot> configuration file.
+If no I<cmd> is given, use IP relay to reset the machine and to get
+the serial output. The IP address of the relay is given by I<addr>
+parameter if specified or by $iprelay_addr variable in the
+configuration file.
+
+If I<cmd> is one of "on" or "off", the IP relay is used to press power
+button for a short (in case of "on") or long (in case of "off") time.
+Then, novaboot exits.
+
+Note: This option is expected to work with HWG-ER02a IP relays.
+
+=item --on, --off
+
+Synonym for --iprelay=on/off.
=item -Q, --qemu=I<qemu-binary>
-Use specific version of qemu binary. The default is 'qemu'.
+The name of qemu binary to use. The default is 'qemu'.
=item --qemu-append=I<flags>
Replace the default qemu flags (QEMU_FLAGS variable or C<-cpu coreduo
-smp 2>) with I<flags> specified here.
-=item --rsync-flags=I<flags>
-
-Specifies which I<flags> are appended to F<rsync> command line when
-copying files as a result of I<--server> option.
-
-=item --scons[=scons command]
-
-Runs I<scons> to build files that are not generated by novaboot
-itself.
-
-=item --scriptmod=I<perl expression>
-
-When novaboot script is read, I<perl expression> is executed for every
-line (in $_ variable). For example, C<novaboot
---scriptmod=s/sigma0/omega6/g> replaces every occurrence of I<sigma0>
-in the script with I<omega6>.
-
-When this option is present, it overrides I<$script_modifier> variable
-from the configuration file, which has the same effect. If this option
-is given multiple times all expressions are evaluated in the command
-line order.
+=back
-=item --server[=[[user@]server:]path]
+=head2 Interaction with the bootloader on the target
-Copy all files needed for booting to a server (implies B<-g> unless
-B<--grub2> is given). The files will be copied to the directory
-I<path>. If the I<path> contains string $NAME, it will be replaced
-with the name of the novaboot script (see also B<--name>).
+See B<--serial>. There will be new options soon.
-Additionally, if $NAME is the last component of the I<path>, a file
-named I<path>/menu.lst (with $NAME removed from the I<path>) will be
-created on the server by concatenating all I<path>/*/menu.lst (with
-$NAME removed from the I<path>) files found on the server.
+=head2 Reception of target's output (e.g. console) on the host system
=item -s, --serial[=device]
-Use serial line to control GRUB bootloader and to get the serial
-output of the machine. The default value is /dev/ttyUSB0.
-
-=item --strip-rom
+Use serial line to control GRUB bootloader and to see the output
+serial output of the machine. The default value is F</dev/ttyUSB0>.
-Strip I<rom://> prefix from command lines and generated config files.
-This is needed for NRE.
+=head2 Termination phase
-=back
+Daemons that were spwned (F<dhcpd> and F<tftpd>) are killed here.
=head1 NOVABOOT SCRIPT SYNTAX
section.
Otherwise, the first word on the line represents the filename
-(relative to the build directory (see I<--build-dir>) of the module to
+(relative to the build directory (see B<--build-dir>) of the module to
load and the remaining words are passed as the command line
parameters.
=head1 CONFIGURATION FILE
Novaboot can read its configuration from a file. Configuration file
-was necessary in early days of novaboot. Nowadays, the attempt is made
+was necessary in early days of novaboot. Nowadays, an attempt is made
to not use the configuration file because it makes certain novaboot
scripts unusable on systems without (or with different) configuration
file. The only recommended use of the configuration file is to specify
custom_options (see bellow).
If you decide to use the configuration file, its default location is
-~/.novaboot, other location can be specified B<-c> parameter or with
-NOVABOOT_CONFIG environment variable. The configuration has perl
-syntax and sets values of certain variables. The current configuration
-can be dumped with B<--dump-config> switch. Some configuration
-variables can be overriden by environment variables (see below) or by
-command line switches.
+~/.novaboot, other location can be specified with the B<-c> switch or
+with the NOVABOOT_CONFIG environment variable. The configuration file
+has perl syntax and should set values of certain Perl variables. The
+current configuration can be dumped with the B<--dump-config> switch.
+Some configuration variables can be overriden by environment variables
+(see below) or by command line switches.
Documentation of some configuration variables follows:
projects / novaboot.git / blobdiff