Page MenuHomeFreeBSD
Files F110709091

D14480.diff
No OneTemporary
Actions

D14480.diff
View Options

Index: head/stand/lua/menu.lua.8
===================================================================
--- head/stand/lua/menu.lua.8
+++ head/stand/lua/menu.lua.8
@@ -0,0 +1,236 @@
+.\"
+.\" 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 .

File Metadata

Mime Type
text/plain
Expires
Sun, Feb 23, 4:08 AM (7 h, 47 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
16787753
Default Alt Text
D14480.diff (6 KB)

Event Timeline