stand/lua/config.lua.8

   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 April 27, 2020
  30 .Dt CONFIG.LUA 8
  31 .Os
  32 .Sh NAME
  33 .Nm config.lua
  34 .Nd FreeBSD config module
  35 .Sh DESCRIPTION
  36 .Nm
  37 contains configuration and module loading functionality.
  38 .Pp
  39 Before hooking into or using the functionality provided by
  40 .Nm ,
  41 it must be included with a statement such as the following:
  42 .Pp
  43 .Dl local config = require("config")
  44 .Ss Exported functions
  45 The following functions are exported from
  46 .Nm :
  47 .Bl -tag -width "config.setCarouselIndex(id, idx)" -offset indent
  48 .It Fn config.getCarouselIndex id
  49 Returns the currently chosen index in the carousel menu entry described by
  50 .Ev id .
  51 See the definition of
  52 .Xr menu.lua 8
  53 for a more in-depth explanation of carousels.
  54 .It Fn config.setCarouselIndex id idx
  55 Set the chosen index for the carousel menu entry described by
  56 .Ev id
  57 to
  58 .Ev idx .
  59 A lookup will be done as needed to determine what value
  60 .Ev idx
  61 actually corresponds to.
  62 .It Fn config.readConfFiles files loaded_files
  63 Process
  64 .Ev files
  65 as if it were
  66 .Ev loader_conf_files .
  67 The caller may should pass in a table as the
  68 .Ev loaded_files
  69 argument, which uses filenames as keys and any non-nil value to indicate that
  70 the file named by the key has been loaded.
  71 .It Fn config.processFile name silent
  72 Process and parse
  73 .Ev name
  74 as a configuration file.
  75 Returns true if
  76 .Ev name
  77 exists and parses without error, false otherwise.
  78 If
  79 .Ev silent
  80 is true,
  81 .Fn config.processFile
  82 will not consider a failure to read the file as a failure.
  83 .It Fn config.parse text
  84 Parse
  85 .Ev text
  86 as a configuration file.
  87 This is used internally by
  88 .Fn config.processFile
  89 to parse the contents of a configuration file.
  90 Returns true if parsing succeeds without error, false if an error occurred.
  91 A message is also printed to the console if an error is encountered.
  92 .It Fn config.loadKernel other_kernel
  93 Attempts to load
  94 .Ev other_kernel
  95 as a kernel.
  96 If
  97 .Ev other_kernel
  98 is unset
  99 .Fn config.loadKernel
 100 will attempt to load
 101 .Dq kernel .
 102 Otherwise, it will try to load
 103 .Dq kernel
 104 first from
 105 .Pa /boot/{other_kernel} ,
 106 then from
 107 .Pa {other_kernel} .
 108 .Pp
 109 The latter is tried in case an absolute path has been specified to the kernel
 110 to use.
 111 .Ev module_path
 112 is amended to include the directory the kernel was found in if either of these
 113 paths result in a loaded kernel.
 114 .Pp
 115 If no kernel was loaded from either of these paths,
 116 .Fn config.loadKernel
 117 will attempt to load a kernel named
 118 .Dq {other_kernel}
 119 from
 120 .Ev module_path
 121 instead of attempting to load a kernel named
 122 .Dq kernel .
 123 .Pp
 124 Returns true if a kernel was loaded, false if no kernel was loaded.
 125 .It Fn config.selectKernel kernel
 126 Set
 127 .Ev kernel
 128 to the kernel that will be loaded when either
 129 .Ic autoboot
 130 or
 131 .Ic boot
 132 are invoked.
 133 This is usually called by the menu system as the kernel selector carousel is
 134 toggled through.
 135 .It Fn config.load file reload
 136 Loads
 137 .Ev file
 138 as a configuration file.
 139 If
 140 .Ev file
 141 is not specified,
 142 .Pa /boot/defaults/loader.conf
 143 is used.
 144 .Fn config.load
 145 will then silently attempt to process any files specified in
 146 .Ev loader_conf_files
 147 after
 148 .Ev file
 149 has been processed.
 150 .Xr nextboot 8
 151 configuration will also be checked as part of
 152 .Fn config.load .
 153 Before returning, all
 154 .Dq config.loaded
 155 hooks will be run if
 156 .Ev reload
 157 is not set to true.
 158 .It Fn config.reload file
 159 Reloads
 160 .Ev file
 161 as a configuration file.
 162 .Fn config.reload
 163 will restore the environment to how it existed before the last config was
 164 loaded, then it will invoke
 165 .Fn config.load file .
 166 Before returning, all
 167 .Dq config.reloaded
 168 hooks will be run.
 169 .It Fn config.loadelf
 170 Loads all ELF objects, the selected kernel as well as any modules configured to
 171 be preloaded in
 172 .Xr loader.conf 5 .
 173 This will be called by the Lua intercepted
 174 .Ic autoboot
 175 and
 176 .Ic boot
 177 commands.
 178 .El
 179 .Ss Defined Hooks
 180 The following hooks are defined in
 181 .Nm :
 182 .Bl -tag -width "config.reloaded" -offset indent
 183 .It config.loaded
 184 .It config.reloaded
 185 .El
 186 .Sh SEE ALSO
 187 .Xr loader.conf 5 ,
 188 .Xr loader 8 ,
 189 .Xr menu.lua 8 ,
 190 .Xr nextboot 8
 191 .Sh AUTHORS
 192 The
 193 .Nm
 194 file was originally written by
 195 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
 196 Later work and this manual page was done by
 197 .An Kyle Evans Aq Mt kevans@FreeBSD.org .