Changeset View
Changeset View
Standalone View
Standalone View
head/stand/lua/menu.lua.8
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" | |||||
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | |||||
.\" | |||||
.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org> | |||||
.\" All rights reserved. | |||||
.\" | |||||
.\" 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 . |