1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 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. 14.\" 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 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.Dd February 23, 2018 30.Dt MENU.LUA 8 31.Os 32.Sh NAME 33.Nm menu.lua 34.Nd FreeBSD dynamic menu boot module 35.Sh DESCRIPTION 36.Nm 37contains the main functionality required to build a dynamic menu system. 38It also contains definitions for the built-in menus, some of which are 39influenced by 40.Xr loader 8 41environment variables. 42.Pp 43Before hooking into the functionality provided by 44.Nm , 45it must be included with a statement such as the following: 46.Pp 47.Dl local menu = require("menu") 48.Ss MENU DEFINITIONS 49Menus are represented in 50.Nm 51as a table. 52That table 53.Sy must 54contain an 55.Va entries 56key. 57.Pp 58If the value of the 59.Va entries 60key is itself a table, then each value in this table defines a single entry in 61this menu. 62See 63.Sx MENU ITEM DEFINITIONS 64for the structure of each entry. 65.Pp 66.Va entries 67may also be a function. 68This function must return a table, each value of which defines a single entry 69in this menu. 70See 71.Sx MENU ITEM DEFINITIONS . 72.Ss MENU ITEM DEFINITIONS 73The following keys may be defined for a menu item: 74.Bl -tag -width disable-module_module -offset indent 75.It Ic entry_type 76The type of this menu entry. 77See 78.Sx MENU ITEM TYPES . 79.It Ic carousel_id 80A unique string id for this carousel. 81A carousel is a menu entry that rotates through a selection of items. 82Used for storage of the carousel's current setting. 83.It Ic visible 84A lambda that returns 85.Dv true 86if this menu item should be visible and 87.Dv false 88if it should not be visible. 89.It Ic items 90A table (or a lambda that returns a table) of the possible choices for this 91carousel. 92.It Ic name 93A string (or a lambda that returns a string) containing the current name of this 94item. 95.It Ic func 96The function executed when this entry is selected. 97Every type except for 98.Ic core.MENU_SEPARATOR 99may have a 100.Ic func . 101.It Ic submenu 102The submenu menu definition to draw when this entry is selected. 103.It Ic alias 104A table of case-sensitive aliases for this menu entry. 105All menu entries that can be selected may have any number of 106.Ic alias 107entries. 108.El 109.Pp 110.Ic entry_type 111is the only required key for every entry type. 112.Ic name 113is required for all entry types except for 114.Ic core.MENU_SEPARATOR . 115.Ss MENU ITEM TYPES 116The menu item type constants are defined in 117.Xr core.lua 8 . 118The following types are available: 119.Bl -tag -width core.MENU_CAROUSEL_ENTRY -offset indent 120.It Ic core.MENU_RETURN 121Return to the parent menu. 122If the current menu is the default menu, 123.Nm 124will exit the menu and begin the autoboot sequence (if applicable). 125This type of menu entry may execute 126.Ic func , 127when selected, and has a 128.Ic name . 129.It Ic core.MENU_ENTRY 130A normal menu entry that executes 131.Ic func 132when selected, and has a 133.Ic name . 134.It Ic core.MENU_SEPARATOR 135A menu entry that serves as a separator. 136It may have a 137.Ic name . 138.It Ic core.MENU_SUBMENU 139A menu entry that opens 140.Ic submenu 141when selected. 142It may have a 143.Ic name . 144.It Ic core.MENU_CAROUSEL_ENTRY 145A menu entry that rotates through 146.Ic items 147like a carousel. 148.Ic func 149is executed when selected, and the callback is passed the choice index, name of 150the current choice, and the table of choices. 151.El 152.Ss EXPORTED MENUS 153The following menus are exported by 154.Nm : 155.Bl -tag -width menu.boot_environments -offset indent 156.It Ic menu.default 157The default menu to draw. 158Set to 159.Ic menu.welcome 160by default. 161.It Ic menu.welcome 162The welcome menu. 163Contains single and multi user boot options, as well as entries to access other 164menus. 165.It Ic menu.boot_options 166The "Boot Options" menu. 167.It Ic menu.boot_environments 168The "Boot Environments" menu. 169This menu is only visible if the system is booted on a ZFS partition and more 170than one boot environment was detected at boot. 171.El 172.Sh EXAMPLES 173To replace the default boot menu with a simple boot menu: 174.Pp 175.Bd -literal -offset indent -compact 176local core = require("core") 177local menu = require("menu") 178 179menu.default = { 180 entries = { 181 { 182 entry_type = core.MENU_ENTRY, 183 name = "Boot", 184 func = core.boot, 185 }, 186 { 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 192 end, 193 func = function(_, _, _) 194 loader.setenv("some_envvar", "some_value") 195 end, 196 }, 197 }, 198} 199.Ed 200.Pp 201To add another option to the welcome menu: 202.Pp 203.Bd -literal -offset indent -compact 204local core = require("core") 205local menu = require("menu") 206 207local welcome_entries = menu.welcome.all_entries 208welcome_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 214 end, 215 func = function(_, _, _) 216 loader.setenv("some_envvar", "some_value") 217 end, 218} 219.Ed 220.Sh SEE ALSO 221.Xr loader.conf 5 , 222.Xr core.lua 8 , 223.Xr loader 8 224.Sh HISTORY 225The 226.Nm 227file first appeared in 228.Fx 12.0 . 229.Sh AUTHORS 230The 231.Nm 232file was originally written by 233.An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . 234Later work and this manual page was done by 235.An Kyle Evans Aq Mt kevans@FreeBSD.org . 236