aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/grub/grubeditor.md103
-rw-r--r--resources/scripts/misc/grubeditor.sh28
-rw-r--r--www/contrib.md6
3 files changed, 133 insertions, 4 deletions
diff --git a/docs/grub/grubeditor.md b/docs/grub/grubeditor.md
new file mode 100644
index 00000000..6a6e8c5f
--- /dev/null
+++ b/docs/grub/grubeditor.md
@@ -0,0 +1,103 @@
+GRUB EDITOR
+===========
+
+Libreboot ROM images now support fluid _grub.cfg_ and _grubtest.cfg_
+configuration editing with the grubeditor.sh script! Instead of manually running
+cbfstool to manipulate these configuration files, this script will handle the
+work for you so you can focus on actually modifying your GRUB configuration
+files to your setup's needs.
+
+At the time of this writing, grubeditor.sh supports extracting and editing
+either the grub.cfg or grubtest.cfg file in any cbfstool-compatible Libreboot
+ROM image that contains these files, even ones that have been previously
+modified. It can also swap these configuration files in an existing ROM image,
+handy if you have a working grubtest.cfg and want to make it the default or if
+you broke the main grub.cfg and know that your grubtest.cfg still works. Lastly,
+it can also run diff on these two configuration files to show you how they
+differ.
+
+Introduction
+============
+
+grubeditor.sh takes a number of options, the only one which is required being a
+valid Libreboot ROM image that uses the GRUB2 payload and contains both
+_grub.cfg_ and _grubtest.cfg_ files. Additional options should come _before_ the
+ROM image file on the command line.
+
+You can call the script the **-h** or **--help** option to view a brief summary
+of the options available. Consider this guide a more extensive version of this
+screen.
+
+grubeditor.sh supports extended getopt, which means that all options have both a
+short and a long form which respectively begin with a single hyphen and a double
+hyphen. You can group together several short options with a single hyphen like
+**-ris** (or not, like **-r -i -s**). Long options should be written as
+standalone arguments.
+
+Lastly, you can check which version of grubeditor.sh you are using with the
+**-v** or **--version** option.
+
+Requirements
+============
+
+grubeditor.sh requires an x86, x86_64, or armv7l environment, since these are
+the environments for which cbfstools binaries are provided. Additionally,
+grubeditor.sh needs a Bash environment with extended getopt functionality that
+can run the **diff** command and write to /tmp. Lastly, the script expects to
+live in the top directory of the Libreboot utilities package so it can properly
+call cbfstool.
+
+Chances are that you already meet these requirements if you are on a Linux
+environment of the listed architectures and downloaded the Libreboot utilities
+package from an official source. If not, it shouldn't be too hard to use a
+Linux LiveCD of your choice which provides these essentials.
+
+Optionally, you should make sure your EDITOR variable is set. Otherwise,
+grubeditor.sh will default to using vi, which may not exist on your system. You
+can override this default or the contents of your EDITOR variable using the
+**-e** or **--editor** command.
+
+Editing configuration files
+===========================
+
+Invoked without any arguments except for the ROM image, grubeditor.sh will
+attempt to extract the _grubtest.cfg_ file from the provided ROM image and
+launch it in your editor of choice. If you make changes to the file,
+grubeditor.sh will incorporate your changes into a new ROM image with the same
+name in the same directory, except that the new ROM file will end with
+".modified". You can then flash this ROM image to your platform's BIOS chip.
+
+If you would prefer to edit the actual _grub.cfg_ configuration file, use the
+**-r** or the **--realcfg** option. Everything else will work the same except
+that your editor will open the _grub.cfg_ instead.
+
+If you would prefer to overwrite your existing ROM image instead of creating a
+new one ending in ".modified" use the **-i** or **--inplace** option.
+Naturally, you can combine this option with the **-r/--realcfg** option
+described above.
+
+Swapping and diffing grub.cfg and grubtest.cfg
+==============================================
+
+grubeditor.sh supports swapping the _grub.cfg_ and _grubtest.cfg_ configuration
+files with the **-s** or **--swap** options. This will create a new ROM image
+alongside the existing ROM image ending with ".modified" which has these files
+swapped. Naturally, you can request this operation overwrite the existing file
+instead using the **-i/--inplace** option.
+
+Lastly, grubeditor.sh supports comparing _grub.cfg_ and _grubtest.cfg_ files for
+differences with the **-d** or **--diffcfg** option. This uses the diff command
+by default, but if you want to use another program (e.g. vimdiff), you can
+specify it with the **-D** or **--differ** option. Note that this mode is only
+intended to show differences in the files and does not support updating the
+configs themselves, so any changes you make in an interactive differ will be
+ignored.
+
+Conclusion
+==========
+
+I hope that grubeditor.sh will significantly ease modifying your configuration
+files in your Libreboot ROM files.
+
+Should you find any bugs or want any feature requests, please don't hesitate to
+email me or bug me on IRC.
diff --git a/resources/scripts/misc/grubeditor.sh b/resources/scripts/misc/grubeditor.sh
index 832e0dc6..f6ccb728 100644
--- a/resources/scripts/misc/grubeditor.sh
+++ b/resources/scripts/misc/grubeditor.sh
@@ -45,6 +45,7 @@
#
# -D | --differ [/path/to/]differ: use /path/to/differ instead of "diff", can
# be an interactive program like vimdiff
+#
# THIS BLOCK IS EXPERIMENTAL
# Allow debugging by running DEBUG= ${0}.
@@ -53,6 +54,9 @@
# -e kills the script if any function returns not-zero
#set -u
+# Version number of script
+geversion="0.1.1"
+
# Define the list of available option in both short and long form.
shortopts="hrie:sdD:"
longopts="help,realcfg,inplace,editor:,swapcfgs,diffcfgs,differ:"
@@ -101,9 +105,14 @@ get_options() {
case "$1" in
-h|--help)
show_help
- # I return non-zero here just so nobody thinks we successfully edited grub.cfg
+ # I return non-zero here just so nobody thinks we successfully edited grub{,test}.cfg
exit 200
;;
+ -v|--version)
+ show_version
+ # I return non-zero here just so nobody thinks we successfully edited grub{,test}.cfg
+ exit 201
+ ;;
-r|--realcfg)
edit_realcfg=1
shift
@@ -307,6 +316,10 @@ existing file
HELPSCREEN
}
+show_version() {
+ echo "${geversion}"
+}
+
swap_configs() {
# Procedure:
# 1. Call cbfstool twice, once each to extract grub.cfg and grubtest.cfg.
@@ -356,12 +369,19 @@ diff_configs() {
# Determine the differ command to use.
find_differ
+ grubcfg="$(random_filer "grubcfg")"
+ testcfg="$(random_filer "testcfg")"
+
# Extract config files from provided romfile.
- "${cbfstool}" "${romfile}" extract -n grub.cfg -f /tmp/grub_tmpdiff.cfg
- "${cbfstool}" "${romfile}" extract -n grubtest.cfg -f /tmp/grubtest_tmpdiff.cfg
+ "${cbfstool}" "${romfile}" extract -n grub.cfg -f "${grubcfg}"
+ "${cbfstool}" "${romfile}" extract -n grubtest.cfg -f "${testcfg}"
# Run the differ command with real as first option, test as second option.
- "${use_differ}" /tmp/grub_tmpdiff.cfg /tmp/grubtest_tmpdiff.cfg
+ "${use_differ}" "${grubcfg}" "${testcfg}"
+
+ # Delete the temporary copies of the configuration files.
+ rm "${grubcfg}"
+ rm "${testcfg}"
}
edit_config() {
diff --git a/www/contrib.md b/www/contrib.md
index 297aedde..b1089a39 100644
--- a/www/contrib.md
+++ b/www/contrib.md
@@ -133,3 +133,9 @@ Vladimir Serbinenko
Ported many of the thinkpads supported in libreboot, to coreboot, and
made many fixes in coreboot which benefited the libreboot project.
Contact **phcoder** in the \#coreboot IRC channel on freenode.
+
+Zyliwax
+-------------------
+
+Wrote the grubeditor.sh script and associated documentation. Contact
+**zyliwax** in the \#libreboot channel.