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")
208 entry_type = core.MENU_ENTRY,
213 local stock_entries = menu.welcome.entries
214 function menu.welcome.entries()
215 local ents = stock_entries()
216 ents[#ents + 1] = my_entry
221 To create a vendor submenu or other vendor menu option,
223 .Ic menu.welcome.all_entires.vendor
226 .Bd -literal -offset indent -compact
227 local core = require("core")
228 local menu = require("menu")
230 -- Fill in with vendor specific entries
231 local vendor_options = {
237 local welcome_entries = menu.welcome.all_entries
238 welcome_entries.vendor = {
239 entry_type = core.MENU_SUBMENU,
240 name = color.highlight("V") .. "endor Options",
241 submenu = vendor_options,
248 In the above example,
250 is a local variable that defines the vendor submenu.
252 To add an additional option, change the
253 .Ic menu.boot_options.entries
255 The following illustrates this concept:
257 .Bd -literal -offset indent -compact
258 -- This is a silly example that rotates local_option through the values
259 -- 0 to 4. local_option would still need to be used elsewhere.
260 local local_option = 0
262 -- The `entries` of a menu may either be a table or a function. In this
263 -- example we're augmenting a menu that just has a static table, but if we
264 -- wanted to be more robust then we would need to instead check the type
265 -- of `stock_options` here to determine our next move.
267 -- If `entries` is a table, then the stock menu system won't be changing it
268 -- so we can just add our menu option as we do below.
270 -- If `entries` is a function, then we would need to provide a new function to
271 -- replace `entries` that does a core.deepCopyTable() of the result and adds
272 -- the below item to it. The deep copy is necessary to avoid duplicating our
273 -- new menu item and allowing the menu to alter its behavior however it pleases.
274 local stock_options = menu.boot_options.entries
275 stock_options[#stock_options + 1] = {
276 entry_type = core.MENU_ENTRY,
278 return color.highlight('L') ..
279 "ocal Option : " .. local_option
282 local_option = (local_option + 1) % 5
293 file first appeared in
298 file was originally written by
299 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
300 Later work and this manual page was done by
301 .An Kyle Evans Aq Mt kevans@FreeBSD.org .