Debian Codegraph @

BUILDING

raw
1 It's pretty straightforward:
2
3 cp $MY_DER_ENCODED_CERT pub.cer
4 make VENDOR_CERT_FILE=pub.cer
5 make EFIDIR=my_esp_dir_name install
6
7 There are a couple of ways to customize the build:
8
9 Install targets:
10 - install
11 installs shim as if to a hard drive, including installing MokManager and
12 fallback appropriately.
13 - install-as-data
14 installs shim files to /usr/share/shim/$(EFI_ARCH)-$(VERSION)/
15
16 Variables you should set to customize the build:
17 - EFIDIR
18 This is the name of the ESP directory. The install targets won't work
19 without it.
20 - DESTDIR
21 This will be prepended to any install targets, so you don't have to
22 install to a live root directory.
23 - DEFAULT_LOADER
24 defaults to \\\\grub$(EFI_ARCH).efi , but you could set it to whatever.
25 Be careful with the leading backslashes, they can be hard to get
26 correct.
27
28 Variables you could set to customize the build:
29 - ENABLE_SHIM_CERT
30 if this variable is defined on the make command line, shim will
31 generate keys during the build and sign MokManager and fallback with
32 them, and the signed version will be what gets installed with the
33 install targets
34 - ENABLE_SHIM_DEVEL
35 If this is set, we look for SHIM_DEVEL_DEBUG instead of SHIM_DEBUG in
36 our debugger delay hook, thus meaning you can have it pause for a
37 debugger only on the development branch and not the OS you need to boot
38 to scp in a new development build. Likewise, we look for
39 SHIM_DEVEL_VERBOSE rather than SHIM_VERBOSE.
40 - DISABLE_REMOVABLE_LOAD_OPTIONS
41 Do not parse load options when invoked as boot*.efi. This prevents boot
42 failures because of unexpected data in boot entries automatically generated
43 by firmware. It breaks loading non-default second-stage loaders when invoked
44 via that path, and requires using a binary named shim*.efi (or really anything
45 else).
46 - REQUIRE_TPM
47 if tpm logging or extends return an error code, treat that as a fatal error.
48 - ARCH
49 This allows you to do a build for a different arch that we support. For
50 instance, on x86_64 you could do "setarch linux32 make ARCH=ia32" to get
51 the ia32 build instead. (DEFAULT_LOADER will be automatically adjusted
52 in that case.)
53 - TOPDIR
54 You can use this along with make -f to build in a subdir. For instance,
55 on an x86_64 machine you could do:
56
57 mkdir build-ia32 build-x64 inst
58 cd build-ia32
59 setarch linux32 make TOPDIR=.. ARCH=ia32 -f ../Makefile
60 setarch linux32 make TOPDIR=.. ARCH=ia32 \
61 DESTDIR=../inst EFIDIR=debian \
62 -f ../Makefile install
63 cd ../build-x64
64 make TOPDIR=.. -f ../Makefile
65 make TOPDIR=.. DESTDIR=../inst EFIDIR=debian \
66 -f ../Makefile install
67
68 That would get you x86_64 and ia32 builds in the "inst" subdir.
69 - OSLABEL
70 This is the label that will be put in BOOT$(EFI_ARCH).CSV for your OS.
71 By default this is the same value as EFIDIR .
72 - POST_PROCESS_PE_FLAGS
73 This allows you to add flags to the invocation of "post-process-pe", for
74 example to disable the NX compatibility flag.
75 - ENABLE_CODESIGN_EKU
76 This changes the certificate validation logic to require Extended Key
77 Usage 1.3.6.1.5.5.7.3.3 ("Code Signing").
78
79 Vendor SBAT data:
80 It will sometimes be requested by reviewers that a build includes extra
81 .sbat data. The mechanism to do so is to add a CSV file in data/ with the
82 name sbat.FOO.csv, where foo is your EFI subdirectory name. The build
83 system will automatically include any such files.
84
85 Building and booting local VM to test shim changes with other 2nd/3rd stages:
86 - pick the target distribution of your choice, currently supported are Fedora/CentOS/Debian/Ubuntu
87 - ensure the package manager for the target distribution is installed locally - dnf+rpm or apt+dpkg
88 - install python3
89 - have mkosi available, either via the distribution, or pip, or having bin/mkosi in PATH from git clone of https://github.com/systemd/mkosi
90 - (one time step) mkosi genkey
91 - mkosi sandbox -- mkosi --firmware-variables mkosi/mkosi.output/ovmf_vars.fd --distribution <distro> qemu
92 - this will build and cache a local VM, build shim in it, and boot it with systemd-boot and a UKI by default
93 - to pick different 2nd/3rd stages, run mkosi sandbox -- mkosi --distribution <distro> --bootloader <2nd stage> --unified-kernel-images <unsigned/no> -f -i build
94
95 # vim:filetype=mail:tw=74