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 June 9, 2018
  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.processFile name silent
  63 Process and parse
  64 .Ev name
  65 as a configuration file.
  66 Returns true if
  67 .Ev name
  68 exists and parses without error, false otherwise.
  69 If
  70 .Ev silent
  71 is true,
  72 .Fn config.processFile
  73 will not consider a failure to read the file as a failure.
  74 .It Fn config.parse text
  75 Parse
  76 .Ev text
  77 as a configuration file.
  78 This is used internally by
  79 .Fn config.processFile
  80 to parse the contents of a configuration file.
  81 Returns true if parsing succeeds without error, false if an error occurred.
  82 A message is also printed to the console if an error is encountered.
  83 .It Fn config.loadKernel other_kernel
  84 Attempts to load
  85 .Ev other_kernel
  86 as a kernel.
  87 If
  88 .Ev other_kernel
  89 is unset
  90 .Fn config.loadKernel
  91 will attempt to load
  92 .Dq kernel .
  93 Otherwise, it will try to load
  94 .Dq kernel
  95 first from
  96 .Pa /boot/{other_kernel} ,
  97 then from
  98 .Pa {other_kernel} .
  99 .Pp
 100 The latter is tried in case an absolute path has been specified to the kernel
 101 to use.
 102 .Ev module_path
 103 is amended to include the directory the kernel was found in if either of these
 104 paths result in a loaded kernel.
 105 .Pp
 106 If no kernel was loaded from either of these paths,
 107 .Fn config.loadKernel
 108 will attempt to load a kernel named
 109 .Dq {other_kernel}
 110 from
 111 .Ev module_path
 112 instead of attempting to load a kernel named
 113 .Dq kernel .
 114 .Pp
 115 Returns true if a kernel was loaded, false if no kernel was loaded.
 116 .It Fn config.selectKernel kernel
 117 Set
 118 .Ev kernel
 119 to the kernel that will be loaded when either
 120 .Ic autoboot
 121 or
 122 .Ic boot
 123 are invoked.
 124 This is usually called by the menu system as the kernel selector carousel is
 125 toggled through.
 126 .It Fn config.load file reload
 127 Loads
 128 .Ev file
 129 as a configuration file.
 130 If
 131 .Ev file
 132 is not specified,
 133 .Pa /boot/defaults/loader.conf
 134 is used.
 135 .Fn config.load
 136 will then silently attempt to process any files specified in
 137 .Ev loader_conf_files
 138 after
 139 .Ev file
 140 has been processed.
 141 .Xr nextboot 8
 142 configuration will also be checked as part of
 143 .Fn config.load .
 144 Before returning, all
 145 .Dq config.loaded
 146 hooks will be run if
 147 .Ev reload
 148 is not set to true.
 149 .It Fn config.reload file
 150 Reloads
 151 .Ev file
 152 as a configuration file.
 153 .Fn config.reload
 154 will restore the environment to how it existed before the last config was
 155 loaded, then it will invoke
 156 .Fn config.load file .
 157 Before returning, all
 158 .Dq config.reloaded
 159 hooks will be run.
 160 .It Fn config.loadelf
 161 Loads all ELF objects, the selected kernel as well as any modules configured to
 162 be preloaded in
 163 .Xr loader.conf 5 .
 164 This will be called by the Lua intercepted
 165 .Ic autoboot
 166 and
 167 .Ic boot
 168 commands.
 169 .El
 170 .Ss Defined Hooks
 171 The following hooks are defined in
 172 .Nm :
 173 .Bl -tag -width "config.reloaded" -offset indent
 174 .It config.loaded
 175 .It config.reloaded
 176 .El
 177 .Sh SEE ALSO
 178 .Xr loader.conf 5 ,
 179 .Xr loader 8 ,
 180 .Xr menu.lua 8 ,
 181 .Xr nextboot 8
 182 .Sh AUTHORS
 183 The
 184 .Nm
 185 file was originally written by
 186 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
 187 Later work and this manual page was done by
 188 .An Kyle Evans Aq Mt kevans@FreeBSD.org .