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