2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nd FreeBSD dynamic menu boot module
38 contains the main functionality required to build a dynamic menu system.
39 It also contains definitions for the built-in menus, some of which are
42 environment variables.
44 Before hooking into the functionality provided by
46 it must be included with a statement such as the following:
48 .Dl local menu = require("menu")
50 Menus are represented in
61 key is itself a table, then each value in this table defines a single entry in
64 .Sx MENU ITEM DEFINITIONS
65 for the structure of each entry.
68 may also be a function.
69 This function must return a table, each value of which defines a single entry
72 .Sx MENU ITEM DEFINITIONS .
73 .Ss MENU ITEM DEFINITIONS
74 The following keys may be defined for a menu item:
75 .Bl -tag -width disable-module_module -offset indent
77 The type of this menu entry.
81 A unique string id for this carousel.
82 A carousel is a menu entry that rotates through a selection of items.
83 Used for storage of the carousel's current setting.
87 if this menu item should be visible and
89 if it should not be visible.
91 A table (or a lambda that returns a table) of the possible choices for this
94 A string (or a lambda that returns a string) containing the current name of this
97 The function executed when this entry is selected.
99 .Ic core.MENU_SEPARATOR
103 The submenu menu definition to draw when this entry is selected.
105 A table of case-sensitive aliases for this menu entry.
106 All menu entries that can be selected may have any number of
112 is the only required key for every entry type.
114 is required for all entry types except for
115 .Ic core.MENU_SEPARATOR .
117 The menu item type constants are defined in
119 The following types are available:
120 .Bl -tag -width core.MENU_CAROUSEL_ENTRY -offset indent
121 .It Ic core.MENU_RETURN
122 Return to the parent menu.
123 If the current menu is the default menu,
125 will exit the menu and begin the autoboot sequence (if applicable).
126 This type of menu entry may execute
128 when selected, and has a
130 .It Ic core.MENU_ENTRY
131 A normal menu entry that executes
133 when selected, and has a
135 .It Ic core.MENU_SEPARATOR
136 A menu entry that serves as a separator.
139 .It Ic core.MENU_SUBMENU
140 A menu entry that opens
145 .It Ic core.MENU_CAROUSEL_ENTRY
146 A menu entry that rotates through
150 is executed when selected, and the callback is passed the choice index, name of
151 the current choice, and the table of choices.
154 The following menus are exported by
156 .Bl -tag -width menu.boot_environments -offset indent
158 The default menu to draw.
164 Contains single and multi user boot options, as well as entries to access other
166 .It Ic menu.boot_options
167 The "Boot Options" menu.
168 .It Ic menu.boot_environments
169 The "Boot Environments" menu.
170 This menu is only visible if the system is booted on a ZFS partition and more
171 than one boot environment was detected at boot.
174 To replace the default boot menu with a simple boot menu:
176 .Bd -literal -offset indent -compact
177 local core = require("core")
178 local menu = require("menu")
183 entry_type = core.MENU_ENTRY,
188 entry_type = core.MENU_CAROUSEL_ENTRY,
189 carousel_id = "unique_boot_entry_name",
190 items = {"NO", "YES"},
191 name = function(_, choice, _)
192 return "Option: " .. choice
194 func = function(_, _, _)
195 loader.setenv("some_envvar", "some_value")
202 To add another option to the welcome menu:
204 .Bd -literal -offset indent -compact
205 local core = require("core")
206 local menu = require("menu")
208 local welcome_entries = menu.welcome.all_entries
209 welcome_entries[#welcome_entries + 1] = {
210 entry_type = core.MENU_CAROUSEL_ENTRY,
211 carousel_id = "unique_boot_entry_name",
212 items = {"NO", "YES"},
213 name = function(_, choice, _)
214 return "Option: " .. choice
216 func = function(_, _, _)
217 loader.setenv("some_envvar", "some_value")
228 file first appeared in
233 file was originally written by
234 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
235 Later work and this manual page was done by
236 .An Kyle Evans Aq Mt kevans@FreeBSD.org .