2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .Nd FreeBSD dynamic menu boot module
37 contains the main functionality required to build a dynamic menu system.
38 It also contains definitions for the built-in menus, some of which are
41 environment variables.
43 Before hooking into the functionality provided by
45 it must be included with a statement such as the following:
47 .Dl local menu = require("menu")
49 Menus are represented in
60 key is itself a table, then each value in this table defines a single entry in
63 .Sx MENU ITEM DEFINITIONS
64 for the structure of each entry.
67 may also be a function.
68 This function must return a table, each value of which defines a single entry
71 .Sx MENU ITEM DEFINITIONS .
72 .Ss MENU ITEM DEFINITIONS
73 The following keys may be defined for a menu item:
74 .Bl -tag -width disable-module_module -offset indent
76 The type of this menu entry.
80 A unique string id for this carousel.
81 A carousel is a menu entry that rotates through a selection of items.
82 Used for storage of the carousel's current setting.
86 if this menu item should be visible and
88 if it should not be visible.
90 A table (or a lambda that returns a table) of the possible choices for this
93 A string (or a lambda that returns a string) containing the current name of this
96 The function executed when this entry is selected.
98 .Ic core.MENU_SEPARATOR
102 The submenu menu definition to draw when this entry is selected.
104 A table of case-sensitive aliases for this menu entry.
105 All menu entries that can be selected may have any number of
111 is the only required key for every entry type.
113 is required for all entry types except for
114 .Ic core.MENU_SEPARATOR .
116 The menu item type constants are defined in
118 The following types are available:
119 .Bl -tag -width core.MENU_CAROUSEL_ENTRY -offset indent
120 .It Ic core.MENU_RETURN
121 Return to the parent menu.
122 If the current menu is the default menu,
124 will exit the menu and begin the autoboot sequence (if applicable).
125 This type of menu entry may execute
127 when selected, and has a
129 .It Ic core.MENU_ENTRY
130 A normal menu entry that executes
132 when selected, and has a
134 .It Ic core.MENU_SEPARATOR
135 A menu entry that serves as a separator.
138 .It Ic core.MENU_SUBMENU
139 A menu entry that opens
144 .It Ic core.MENU_CAROUSEL_ENTRY
145 A menu entry that rotates through
149 is executed when selected, and the callback is passed the choice index, name of
150 the current choice, and the table of choices.
153 The following menus are exported by
155 .Bl -tag -width menu.boot_environments -offset indent
157 The default menu to draw.
163 Contains single and multi user boot options, as well as entries to access other
165 .It Ic menu.boot_options
166 The "Boot Options" menu.
167 .It Ic menu.boot_environments
168 The "Boot Environments" menu.
169 This menu is only visible if the system is booted on a ZFS partition and more
170 than one boot environment was detected at boot.
173 To replace the default boot menu with a simple boot menu:
175 .Bd -literal -offset indent -compact
176 local core = require("core")
177 local menu = require("menu")
182 entry_type = core.MENU_ENTRY,
187 entry_type = core.MENU_CAROUSEL_ENTRY,
188 carousel_id = "unique_boot_entry_name",
189 items = {"NO", "YES"},
190 name = function(_, choice, _)
191 return "Option: " .. choice
193 func = function(_, _, _)
194 loader.setenv("some_envvar", "some_value")
201 To add another option to the welcome menu:
203 .Bd -literal -offset indent -compact
204 local core = require("core")
205 local menu = require("menu")
207 local welcome_entries = menu.welcome.all_entries
208 welcome_entries[#welcome_entries + 1] = {
209 entry_type = core.MENU_CAROUSEL_ENTRY,
210 carousel_id = "unique_boot_entry_name",
211 items = {"NO", "YES"},
212 name = function(_, choice, _)
213 return "Option: " .. choice
215 func = function(_, _, _)
216 loader.setenv("some_envvar", "some_value")
227 file first appeared in
232 file was originally written by
233 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
234 Later work and this manual page was done by
235 .An Kyle Evans Aq Mt kevans@FreeBSD.org .