236 lines
6.3 KiB
Groff
236 lines
6.3 KiB
Groff
|
.\"
|
||
|
|
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
|
||
|
|
.\"
|
||
|
|
.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
|
||
|
|
.\"
|
||
|
|
.\" Redistribution and use in source and binary forms, with or without
|
||
|
|
.\" modification, are permitted provided that the following conditions
|
||
|
|
.\" are met:
|
||
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer.
|
||
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
||
|
|
.\" documentation and/or other materials provided with the distribution.
|
||
|
|
.\"
|
||
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||
|
|
.\" SUCH DAMAGE.
|
||
|
|
.\"
|
||
|
|
.\" $FreeBSD$
|
||
|
|
.\"
|
||
|
|
.Dd February 23, 2018
|
||
|
|
.Dt MENU.LUA 8
|
||
|
|
.Os
|
||
|
|
.Sh NAME
|
||
|
|
.Nm menu.lua
|
||
|
|
.Nd FreeBSD dynamic menu boot module
|
||
|
|
.Sh DESCRIPTION
|
||
|
|
.Nm
|
||
|
|
contains the main functionality required to build a dynamic menu system.
|
||
|
|
It also contains definitions for the built-in menus, some of which are
|
||
|
|
influenced by
|
||
|
|
.Xr loader 8
|
||
|
|
environment variables.
|
||
|
|
.Pp
|
||
|
|
Before hooking into the functionality provided by
|
||
|
|
.Nm ,
|
||
|
|
it must be included with a statement such as the following:
|
||
|
|
.Pp
|
||
|
|
.Dl local menu = require("menu")
|
||
|
|
.Ss MENU DEFINITIONS
|
||
|
|
Menus are represented in
|
||
|
|
.Nm
|
||
|
|
as a table.
|
||
|
|
That table
|
||
|
|
.Sy must
|
||
|
|
contain an
|
||
|
|
.Va entries
|
||
|
|
key.
|
||
|
|
.Pp
|
||
|
|
If the value of the
|
||
|
|
.Va entries
|
||
|
|
key is itself a table, then each value in this table defines a single entry in
|
||
|
|
this menu.
|
||
|
|
See
|
||
|
|
.Sx MENU ITEM DEFINITIONS
|
||
|
|
for the structure of each entry.
|
||
|
|
.Pp
|
||
|
|
.Va entries
|
||
|
|
may also be a function.
|
||
|
|
This function must return a table, each value of which defines a single entry
|
||
|
|
in this menu.
|
||
|
|
See
|
||
|
|
.Sx MENU ITEM DEFINITIONS .
|
||
|
|
.Ss MENU ITEM DEFINITIONS
|
||
|
|
The following keys may be defined for a menu item:
|
||
|
|
.Bl -tag -width disable-module_module -offset indent
|
||
|
|
.It Ic entry_type
|
||
|
|
The type of this menu entry.
|
||
|
|
See
|
||
|
|
.Sx MENU ITEM TYPES .
|
||
|
|
.It Ic carousel_id
|
||
|
|
A unique string id for this carousel.
|
||
|
|
A carousel is a menu entry that rotates through a selection of items.
|
||
|
|
Used for storage of the carousel's current setting.
|
||
|
|
.It Ic visible
|
||
|
|
A lambda that returns
|
||
|
|
.Dv true
|
||
|
|
if this menu item should be visible and
|
||
|
|
.Dv false
|
||
|
|
if it should not be visible.
|
||
|
|
.It Ic items
|
||
|
|
A table (or a lambda that returns a table) of the possible choices for this
|
||
|
|
carousel.
|
||
|
|
.It Ic name
|
||
|
|
A string (or a lambda that returns a string) containing the current name of this
|
||
|
|
item.
|
||
|
|
.It Ic func
|
||
|
|
The function executed when this entry is selected.
|
||
|
|
Every type except for
|
||
|
|
.Ic core.MENU_SEPARATOR
|
||
|
|
may have a
|
||
|
|
.Ic func .
|
||
|
|
.It Ic submenu
|
||
|
|
The submenu menu definition to draw when this entry is selected.
|
||
|
|
.It Ic alias
|
||
|
|
A table of case-sensitive aliases for this menu entry.
|
||
|
|
All menu entries that can be selected may have any number of
|
||
|
|
.Ic alias
|
||
|
|
entries.
|
||
|
|
.El
|
||
|
|
.Pp
|
||
|
|
.Ic entry_type
|
||
|
|
is the only required key for every entry type.
|
||
|
|
.Ic name
|
||
|
|
is required for all entry types except for
|
||
|
|
.Ic core.MENU_SEPARATOR .
|
||
|
|
.Ss MENU ITEM TYPES
|
||
|
|
The menu item type constants are defined in
|
||
|
|
.Xr core.lua 8 .
|
||
|
|
The following types are available:
|
||
|
|
.Bl -tag -width core.MENU_CAROUSEL_ENTRY -offset indent
|
||
|
|
.It Ic core.MENU_RETURN
|
||
|
|
Return to the parent menu.
|
||
|
|
If the current menu is the default menu,
|
||
|
|
.Nm
|
||
|
|
will exit the menu and begin the autoboot sequence (if applicable).
|
||
|
|
This type of menu entry may execute
|
||
|
|
.Ic func ,
|
||
|
|
when selected, and has a
|
||
|
|
.Ic name .
|
||
|
|
.It Ic core.MENU_ENTRY
|
||
|
|
A normal menu entry that executes
|
||
|
|
.Ic func
|
||
|
|
when selected, and has a
|
||
|
|
.Ic name .
|
||
|
|
.It Ic core.MENU_SEPARATOR
|
||
|
|
A menu entry that serves as a separator.
|
||
|
|
It may have a
|
||
|
|
.Ic name .
|
||
|
|
.It Ic core.MENU_SUBMENU
|
||
|
|
A menu entry that opens
|
||
|
|
.Ic submenu
|
||
|
|
when selected.
|
||
|
|
It may have a
|
||
|
|
.Ic name .
|
||
|
|
.It Ic core.MENU_CAROUSEL_ENTRY
|
||
|
|
A menu entry that rotates through
|
||
|
|
.Ic items
|
||
|
|
like a carousel.
|
||
|
|
.Ic func
|
||
|
|
is executed when selected, and the callback is passed the choice index, name of
|
||
|
|
the current choice, and the table of choices.
|
||
|
|
.El
|
||
|
|
.Ss EXPORTED MENUS
|
||
|
|
The following menus are exported by
|
||
|
|
.Nm :
|
||
|
|
.Bl -tag -width menu.boot_environments -offset indent
|
||
|
|
.It Ic menu.default
|
||
|
|
The default menu to draw.
|
||
|
|
Set to
|
||
|
|
.Ic menu.welcome
|
||
|
|
by default.
|
||
|
|
.It Ic menu.welcome
|
||
|
|
The welcome menu.
|
||
|
|
Contains single and multi user boot options, as well as entries to access other
|
||
|
|
menus.
|
||
|
|
.It Ic menu.boot_options
|
||
|
|
The "Boot Options" menu.
|
||
|
|
.It Ic menu.boot_environments
|
||
|
|
The "Boot Environments" menu.
|
||
|
|
This menu is only visible if the system is booted on a ZFS partition and more
|
||
|
|
than one boot environment was detected at boot.
|
||
|
|
.El
|
||
|
|
.Sh EXAMPLES
|
||
|
|
To replace the default boot menu with a simple boot menu:
|
||
|
|
.Pp
|
||
|
|
.Bd -literal -offset indent -compact
|
||
|
|
local core = require("core")
|
||
|
|
local menu = require("menu")
|
||
|
|
|
||
|
|
menu.default = {
|
||
|
|
entries = {
|
||
|
|
{
|
||
|
|
entry_type = core.MENU_ENTRY,
|
||
|
|
name = "Boot",
|
||
|
|
func = core.boot,
|
||
|
|
},
|
||
|
|
{
|
||
|
|
entry_type = core.MENU_CAROUSEL_ENTRY,
|
||
|
|
carousel_id = "unique_boot_entry_name",
|
||
|
|
items = {"NO", "YES"},
|
||
|
|
name = function(_, choice, _)
|
||
|
|
return "Option: " .. choice
|
||
|
|
end,
|
||
|
|
func = function(_, _, _)
|
||
|
|
loader.setenv("some_envvar", "some_value")
|
||
|
|
end,
|
||
|
|
},
|
||
|
|
},
|
||
|
|
}
|
||
|
|
.Ed
|
||
|
|
.Pp
|
||
|
|
To add another option to the welcome menu:
|
||
|
|
.Pp
|
||
|
|
.Bd -literal -offset indent -compact
|
||
|
|
local core = require("core")
|
||
|
|
local menu = require("menu")
|
||
|
|
|
||
|
|
local welcome_entries = menu.welcome.all_entries
|
||
|
|
welcome_entries[#welcome_entries + 1] = {
|
||
|
|
entry_type = core.MENU_CAROUSEL_ENTRY,
|
||
|
|
carousel_id = "unique_boot_entry_name",
|
||
|
|
items = {"NO", "YES"},
|
||
|
|
name = function(_, choice, _)
|
||
|
|
return "Option: " .. choice
|
||
|
|
end,
|
||
|
|
func = function(_, _, _)
|
||
|
|
loader.setenv("some_envvar", "some_value")
|
||
|
|
end,
|
||
|
|
}
|
||
|
|
.Ed
|
||
|
|
.Sh SEE ALSO
|
||
|
|
.Xr loader.conf 5 ,
|
||
|
|
.Xr core.lua 8 ,
|
||
|
|
.Xr loader 8
|
||
|
|
.Sh HISTORY
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
file first appeared in
|
||
|
|
.Fx 12.0 .
|
||
|
|
.Sh AUTHORS
|
||
|
|
The
|
||
|
|
.Nm
|
||
|
|
file was originally written by
|
||
|
|
.An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
|
||
|
|
Later work and this manual page was done by
|
||
|
|
.An Kyle Evans Aq Mt kevans@FreeBSD.org .
|