MENU.LUA(8) FreeBSD System Manager's Manual MENU.LUA(8)
NAME
menu.lua - FreeBSD dynamic menu boot module
DESCRIPTION
menu.lua 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 loader(8) environment variables.
Before hooking into the functionality provided by menu.lua, it must be
included with a statement such as the following:
local menu = require("menu")
MENU DEFINITIONS
Menus are represented in menu.lua as a table. That table must contain an
entries key.
If the value of the entries key is itself a table, then each value in
this table defines a single entry in this menu. See MENU ITEM
DEFINITIONS for the structure of each entry.
entries may also be a function. This function must return a table, each
value of which defines a single entry in this menu. See MENU ITEM
DEFINITIONS.
MENU ITEM DEFINITIONS
The following keys may be defined for a menu item:
entry_type The type of this menu entry. See MENU ITEM
TYPES.
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.
visible A lambda that returns true if this menu item
should be visible and false if it should not
be visible.
items A table (or a lambda that returns a table)
of the possible choices for this carousel.
name A string (or a lambda that returns a string)
containing the current name of this item.
func The function executed when this entry is
selected. Every type except for
core.MENU_SEPARATOR may have a func.
submenu The submenu menu definition to draw when
this entry is selected.
alias A table of case-sensitive aliases for this
menu entry. All menu entries that can be
selected may have any number of alias
entries.
entry_type is the only required key for every entry type. name is
required for all entry types except for core.MENU_SEPARATOR.
MENU ITEM TYPES
The menu item type constants are defined in core.lua(8). The following
types are available:
core.MENU_RETURN Return to the parent menu. If the
current menu is the default menu,
menu.lua will exit the menu and begin the
autoboot sequence (if applicable). This
type of menu entry may execute func, when
selected, and has a name.
core.MENU_ENTRY A normal menu entry that executes func
when selected, and has a name.
core.MENU_SEPARATOR A menu entry that serves as a separator.
It may have a name.
core.MENU_SUBMENU A menu entry that opens submenu when
selected. It may have a name.
core.MENU_CAROUSEL_ENTRY A menu entry that rotates through items
like a carousel. func is executed when
selected, and the callback is passed the
choice index, name of the current choice,
and the table of choices.
EXPORTED MENUS
The following menus are exported by menu.lua:
menu.default The default menu to draw. Set to
menu.welcome by default.
menu.welcome The welcome menu. Contains single and
multi user boot options, as well as entries
to access other menus.
menu.boot_options The "Boot Options" menu.
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.
EXAMPLES
To replace the default boot menu with a simple boot menu:
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,
},
},
}
To add another option to the welcome menu:
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,
}
SEE ALSO
loader.conf(5), core.lua(8), loader(8)
HISTORY
The menu.lua file first appeared in FreeBSD 12.0.
AUTHORS
The menu.lua file was originally written by Pedro Souza
<pedrosouza@FreeBSD.org>. Later work and this manual page was done by
Kyle Evans <kevans@FreeBSD.org>.
FreeBSD 13.1-RELEASE-p6 February 23, 2018 FreeBSD 13.1-RELEASE-p6
man2web Home...