-
-
Notifications
You must be signed in to change notification settings - Fork 164
/
Makefile
1098 lines (919 loc) 路 50.6 KB
/
Makefile
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
### This makefile is the top-level build script that builds all the crates in subdirectories
### and combines them into the final OS .iso image.
### It also provides convenient targets for running and debugging Theseus and using GDB on your host computer.
SHELL := /usr/bin/env bash
## Disable parallelism for this Makefile since it breaks the build,
## as our dependencies aren't perfectly specified for each target.
## Cargo already handles build parallelism for us anyway.
.NOTPARALLEL:
## Override the locale as building on non-English systems may fail.
## Or even worse: it might build, but not boot.
## Overriding LC_ALL instead throws bash warnings.
## C.UTF-8 should be available on all modern glibc systems.
export override LANG="C.UTF-8"
## most of the variables used below are defined in Config.mk
include cfg/Config.mk
## By default, we just build the standard OS image via the `iso` target.
.DEFAULT_GOAL := iso
## Default values for various configuration options.
debug ?= none
net ?= none
merge_sections ?= yes
bootloader ?= grub
## aarch64 only supports booting via UEFI
ifeq ($(ARCH),aarch64)
boot_spec = uefi
else
boot_spec ?= bios
endif
## Set up configuration based on the chosen bootloader specification (boot_spec).
export override FEATURES+=--features nano_core/$(boot_spec)
ifeq ($(boot_spec), bios)
ISO_EXTENSION := iso
else ifeq ($(boot_spec), uefi)
## Disable the default "bios" feature of the nano_core
export override FEATURES+=--no-default-features
ISO_EXTENSION := efi
else
$(error Error:unsupported option "boot_spec=$(boot_spec)". Options are 'bios' or 'uefi')
endif
## test for Windows Subsystem for Linux (Linux on Windows)
IS_WSL = $(shell grep -is 'microsoft' /proc/version)
###################################################################################################
### Basic directory/file path definitions used throughout the makefile.
###################################################################################################
BUILD_DIR := $(ROOT_DIR)/build
NANO_CORE_BUILD_DIR := $(BUILD_DIR)/nano_core
iso := $(BUILD_DIR)/theseus-$(ARCH).$(ISO_EXTENSION)
ISOFILES := $(BUILD_DIR)/isofiles
OBJECT_FILES_BUILD_DIR := $(ISOFILES)/modules
DEBUG_SYMBOLS_DIR := $(BUILD_DIR)/debug_symbols
TARGET_DEPS_DIR := $(ROOT_DIR)/target/$(TARGET)/$(BUILD_MODE)/deps
DEPS_BUILD_DIR := $(BUILD_DIR)/deps
HOST_DEPS_DIR := $(DEPS_BUILD_DIR)/host_deps
DEPS_SYSROOT_DIR := $(DEPS_BUILD_DIR)/sysroot
THESEUS_BUILD_TOML := $(DEPS_BUILD_DIR)/TheseusBuild.toml
THESEUS_CARGO := $(ROOT_DIR)/tools/theseus_cargo
THESEUS_CARGO_BIN := $(THESEUS_CARGO)/bin/theseus_cargo
EXTRA_FILES := $(ROOT_DIR)/extra_files
LIMINE_DIR := $(ROOT_DIR)/limine-prebuilt
### Set up tool names/locations for cross-compiling on a Mac OS / macOS host (Darwin).
UNAME = $(shell uname -s)
ifeq ($(UNAME),Darwin)
CROSS = $(ARCH)-elf-
## macOS uses a different unmounting utility
UNMOUNT = diskutil unmount
USB_DRIVES = $(shell diskutil list external | grep -s "/dev/" | awk '{print $$1}')
else
## Handle building for aarch64 on x86_64 Linux/WSL
ifeq ($(ARCH),aarch64)
CROSS = aarch64-linux-gnu-
endif
## Just use normal umount on Linux/WSL
UNMOUNT = umount
USB_DRIVES = $(shell lsblk -O | grep -i usb | awk '{print $$2}' | grep --color=never '[^0-9]$$')
endif
### Handle multiple bootloader options and ensure the corresponding tools are installed.
ifeq ($(boot_spec),uefi)
## A bootloader isn't required with UEFI.
else ifeq ($(bootloader),grub)
## Look for `grub-mkrescue` (Debian-like distros) or `grub2-mkrescue` (Fedora)
ifneq (,$(shell command -v grub-mkrescue))
GRUB_MKRESCUE = grub-mkrescue
else ifneq (,$(shell command -v grub2-mkrescue))
GRUB_MKRESCUE = grub2-mkrescue
else
$(error Error: could not find 'grub-mkrescue' or 'grub2-mkrescue', please install 'grub' or 'grub2')
endif
else ifeq ($(bootloader),limine)
## Check if the limine directory exists.
ifneq (,$(wildcard $(LIMINE_DIR)/.))
export override FEATURES += --features extract_boot_modules
else
$(error Error: missing '$(LIMINE_DIR)' directory! Please follow the limine instructions in the README)
endif
else
$(error Error: unsupported option "bootloader=$(bootloader)". Options are 'grub' or 'limine')
endif
###################################################################################################
### This section contains targets to actually build Theseus components and create an iso file.
###################################################################################################
## The linker script applied to each output file in $(OBJECT_FILES_BUILD_DIR).
partial_relinking_script := cfg/partial_linking_combine_sections.ld
## The default file path where cargo outputs the nano_core's static library.
nano_core_static_lib := $(ROOT_DIR)/target/$(TARGET)/$(BUILD_MODE)/libnano_core.a
## The output file path of the fully-linked nano_core kernel binary.
nano_core_binary := $(NANO_CORE_BUILD_DIR)/nano_core-$(ARCH).bin
## The linker script for linking the `nano_core_binary` with the compiled assembly files.
linker_script := $(ROOT_DIR)/kernel/nano_core/linker_higher_half-$(ARCH).ld
efi_firmware := $(BUILD_DIR)/$(OVMF_FILE)
ifeq ($(ARCH),x86_64)
## The assembly files compiled by the nano_core build script.
compiled_nano_core_asm := $(NANO_CORE_BUILD_DIR)/compiled_asm/$(boot_spec)/*.o
endif
## Specify which crates should be considered as application-level libraries.
## These crates can be instantiated multiply (per-task, per-namespace) rather than once (system-wide);
## they will only be multiply instantiated if they have data/bss sections.
## Ideally we would do this with a script that analyzes dependencies to see if a crate is only used by application crates,
## but I haven't had time yet to develop that script. It would be fairly straightforward using a tool like `cargo deps`.
## So, for now, we just do it manually.
## You can execute this to view dependencies to help you out:
## `cd kernel/nano_core && cargo deps --include-orphans --no-transitive-deps | dot -Tpdf > /tmp/graph.pdf && xdg-open /tmp/graph.pdf`
EXTRA_APP_CRATE_NAMES += getopts unicode_width
# get all the subdirectories in applications/, i.e., the list of application crates
APP_CRATE_NAMES := $(notdir $(wildcard applications/*))
# exclude the build directory
APP_CRATE_NAMES := $(filter-out build/. target/., $(APP_CRATE_NAMES))
# exclude hidden directories starting with a "."
APP_CRATE_NAMES := $(filter-out .*/, $(APP_CRATE_NAMES))
# remove the trailing /. on each name
APP_CRATE_NAMES := $(patsubst %/., %, $(APP_CRATE_NAMES))
APP_CRATE_NAMES += $(EXTRA_APP_CRATE_NAMES)
### PHONY is the list of targets that *always* get rebuilt regardless of dependent files' modification timestamps.
### Most targets are PHONY because cargo itself handles whether or not to rebuild the Rust code base.
.PHONY: all full \
check-usb \
clean clean-doc clean-old-build \
orun orun_pause run run_pause iso build cargo copy_kernel $(bootloader) extra_files \
libtheseus \
simd_personality_sse build_sse simd_personality_avx build_avx \
gdb gdb_aarch64 \
clippy doc docs view-doc view-docs book view-book
### If we compile for SIMD targets newer than SSE (e.g., AVX or newer),
### then we need to define a preprocessor variable
### that will cause the AVX flag to be enabled in the boot-up assembly code.
ifneq (,$(findstring avx,$(TARGET)))
export override CFLAGS+=-DENABLE_AVX
endif
### Convert `THESEUS_CONFIG` values into `RUSTFLAGS` by prepending "--cfg " to each one.
### Note: this change to RUSTFLAGS is exported as an external shell environment variable
### in order to make it easy to pass to sub-make invocations.
### However, this means we must not explicitly not use it for `cargo run` tool invocations,
### because those should be built as normal for the host OS environment.
export override RUSTFLAGS += $(patsubst %,--cfg %, $(THESEUS_CONFIG))
### Convenience targets for building the entire Theseus workspace
### with all optional components included.
### See `theseus_features/src/lib.rs` for more details on what this includes.
all: full
full : export override FEATURES += --features theseus_features/everything
ifeq (,$(findstring --workspace,$(FEATURES)))
full : export override FEATURES += --workspace
endif
full: iso
### Convenience target for building the ISO using the below $(iso) target
iso: $(iso)
### This target builds an .iso OS image from all of the compiled crates.
$(iso): clean-old-build build extra_files copy_kernel $(iso)-$(boot_spec)
## This target is invoked by the '$(iso)' target when boot_spec = 'bios'.
$(iso)-bios: $(bootloader)
## This target is invoked by the '$(iso)' target when boot_spec = 'uefi'.
$(iso)-uefi: $(efi_firmware)
@cargo run \
--release \
-Z bindeps \
--manifest-path $(ROOT_DIR)/tools/uefi_builder/$(ARCH)/Cargo.toml -- \
--kernel $(nano_core_binary) \
--modules $(OBJECT_FILES_BUILD_DIR) \
--efi-image $(iso)
## Copy the kernel boot image into the proper ISOFILES directory.
## Should be invoked after building all Theseus kernel/application crates.
copy_kernel:
@mkdir -p $(ISOFILES)/boot/
@cp $(nano_core_binary) $(ISOFILES)/boot/kernel.bin
## This first invokes the make target that runs the actual compiler, and then copies all object files into the build dir.
## This also classifies crate object files into either "application" or "kernel" crates:
## -- an application crate is any executable application in the `applications/` directory, or a library crate that is ONLY used by other applications,
## -- a kernel crate is any crate in the `kernel/` directory, or any other crates that are used by kernel crates.
## Obviously, if a crate is used by both other application crates and by kernel crates, it is still a kernel crate.
## Then, we give all kernel crate object files the KERNEL_PREFIX and all application crate object files the APP_PREFIX.
build: $(nano_core_binary)
## Here, the main Rust build has just occurred.
##
## First, if an .rlib archive contains multiple object files, we need to extract them all out of the archive
## and combine them into one object file using partial linking (`ld -r ...`), overwriting the rustc-emitted .o file.
## Note: we skip "normal" .rlib archives that have 2 members: a single .o object file and a single .rmeta file.
## Note: the below line with `cut` simply removes the `lib` prefix and the `.rlib` suffix from the file name.
@for f in $(shell find $(TARGET_DEPS_DIR)/ -name "*.rlib"); do \
if [ `$(CROSS)ar -t $${f} | wc -l` != "2" ]; then \
echo -e "\033[1;34mUnarchiving multi-file rlib: \033[0m $${f}" \
&& mkdir -p "$(BUILD_DIR)/extracted_rlibs/`basename $${f}`-unpacked/" \
&& $(CROSS)ar -xo --output "$(BUILD_DIR)/extracted_rlibs/`basename $${f}`-unpacked/" $${f} \
&& $(CROSS)ld -r \
--output "$(TARGET_DEPS_DIR)/`basename $${f} | cut -c 4- | rev | cut -c 6- | rev`.o" \
$$(find $(BUILD_DIR)/extracted_rlibs/$$(basename $${f})-unpacked/ -name "*.o") ; \
fi & \
done; wait
## Second, copy all object files into the main build directory and prepend the kernel or app prefix appropriately.
@RUSTFLAGS="" cargo run --release --manifest-path $(ROOT_DIR)/tools/copy_latest_crate_objects/Cargo.toml -- \
-i "$(TARGET_DEPS_DIR)" \
--output-objects $(OBJECT_FILES_BUILD_DIR) \
--output-deps $(DEPS_BUILD_DIR) \
--output-sysroot $(DEPS_SYSROOT_DIR)/lib/rustlib/$(TARGET)/lib \
-k ./kernel \
-a ./applications \
--kernel-prefix $(KERNEL_PREFIX) \
--app-prefix $(APP_PREFIX) \
-e "$(EXTRA_APP_CRATE_NAMES) libtheseus"
## Third, perform partial linking on each object file, which shrinks their size
## and most importantly, accelerates their loading and linking at runtime.
## We also remove the unnecessary GCC_except_table* symbols from the symbol tables.
ifeq ($(merge_sections),yes)
@for f in $(OBJECT_FILES_BUILD_DIR)/*.o ; do \
$(CROSS)ld -r -T $(partial_relinking_script) $${f} -o $${f}_relinked \
&& mv $${f}_relinked $${f} \
&& $(CROSS)strip --wildcard --strip-symbol=GCC_except_table* $${f} & \
done; wait
else ifeq ($(merge_sections),no)
# do nothing, leave the object files as is, with separate function/data sections
else
$(error Error: unsupported option "merge_sections=$(merge_sections)". Options are 'yes' or 'no')
endif
## Fourth, create the items needed for future out-of-tree builds that depend upon the parameters of this current build.
## This includes the target file, host OS dependencies (proc macros, etc).,
## and most importantly, a TOML file to describe these and other config variables.
@rm -rf $(THESEUS_BUILD_TOML)
@cp -f $(CFG_DIR)/$(TARGET).json $(DEPS_BUILD_DIR)/
@mkdir -p $(HOST_DEPS_DIR)
@cp -rf ./target/$(BUILD_MODE)/deps/* $(HOST_DEPS_DIR)/
@echo -e 'target = "$(TARGET)"' >> $(THESEUS_BUILD_TOML)
@echo -e 'sysroot = "./sysroot"' >> $(THESEUS_BUILD_TOML)
@echo -e 'rustflags = "$(RUSTFLAGS)"' >> $(THESEUS_BUILD_TOML)
@echo -e 'cargoflags = "$(CARGOFLAGS)"' >> $(THESEUS_BUILD_TOML)
@echo -e 'features = "$(FEATURES)"' >> $(THESEUS_BUILD_TOML)
@echo -e 'host_deps = "./host_deps"' >> $(THESEUS_BUILD_TOML)
## Fifth, strip debug information if requested. This reduces object file size, improving load times and reducing memory usage.
@mkdir -p $(DEBUG_SYMBOLS_DIR)
ifeq ($(debug),full)
# don't strip any files
else ifeq ($(debug),none)
# strip all files
@for f in $(OBJECT_FILES_BUILD_DIR)/*.o $(nano_core_binary) ; do \
dbg_file=$(DEBUG_SYMBOLS_DIR)/`basename $${f}`.dbg \
&& cp $${f} $${dbg_file} \
&& $(CROSS)strip --only-keep-debug $${dbg_file} \
&& $(CROSS)strip --strip-debug $${f} & \
done; wait
else ifeq ($(debug),base)
# strip all object files but the base kernel
@for f in $(OBJECT_FILES_BUILD_DIR)/*.o ; do \
dbg_file=$(DEBUG_SYMBOLS_DIR)/`basename $${f}`.dbg \
&& cp $${f} $${dbg_file} \
&& $(CROSS)strip --only-keep-debug $${dbg_file} \
&& $(CROSS)strip --strip-debug $${f} & \
done; wait
else
$(error Error: unsupported option "debug=$(debug)". Options are 'full', 'none', or 'base')
endif
## Sixth, fix up CPU local sections.
@echo -e "Parsing CPU local sections"
@cargo run --release --manifest-path $(ROOT_DIR)/tools/elf_cls/Cargo.toml -- $(ARCH) --dir $(OBJECT_FILES_BUILD_DIR)
#############################
### end of "build" target ###
#############################
## This target invokes the actual Rust build process via `cargo`.
cargo:
@mkdir -p $(BUILD_DIR)
@mkdir -p $(NANO_CORE_BUILD_DIR)
@mkdir -p $(OBJECT_FILES_BUILD_DIR)
@mkdir -p $(DEPS_BUILD_DIR)
ifneq (,$(findstring vga_text_mode, $(THESEUS_CONFIG)))
$(eval CFLAGS += -DVGA_TEXT_MODE)
endif
@echo -e "\n=================== BUILDING ALL CRATES ==================="
@echo -e "\t TARGET: \"$(TARGET)\""
@echo -e "\t KERNEL_PREFIX: \"$(KERNEL_PREFIX)\""
@echo -e "\t APP_PREFIX: \"$(APP_PREFIX)\""
@echo -e "\t CFLAGS: \"$(CFLAGS)\""
@echo -e "\t THESEUS_CONFIG (before build.rs script): \"$(THESEUS_CONFIG)\""
THESEUS_CFLAGS='$(CFLAGS)' THESEUS_NANO_CORE_BUILD_DIR='$(NANO_CORE_BUILD_DIR)' RUST_TARGET_PATH='$(CFG_DIR)' RUSTFLAGS='$(RUSTFLAGS)' cargo build $(CARGOFLAGS) $(FEATURES) $(BUILD_STD_CARGOFLAGS) --target $(TARGET)
## We tried using the "cargo rustc" command here instead of "cargo build" to avoid cargo unnecessarily rebuilding core/alloc crates,
## But it doesn't really seem to work (it's not the cause of cargo rebuilding everything).
## For the "cargo rustc" command below, all of the arguments to cargo come before the "--",
## whereas all of the arguments to rustc come after the "--".
# for kd in $(KERNEL_CRATE_NAMES) ; do \
# cd $${kd} ; \
# echo -e "\n========= BUILDING KERNEL CRATE $${kd} ==========\n" ; \
# RUST_TARGET_PATH='$(CFG_DIR)' RUSTFLAGS='$(RUSTFLAGS)' \
# cargo rustc \
# $(CARGOFLAGS) \
# $(RUST_FEATURES) \
# --target $(TARGET) ; \
# cd .. ; \
# done
# for app in $(APP_CRATE_NAMES) ; do \
# cd $${app} ; \
# RUST_TARGET_PATH='$(CFG_DIR)' RUSTFLAGS='$(RUSTFLAGS)' \
# cargo rustc \
# $(CARGOFLAGS) \
# --target $(TARGET) \
# -- \
# $(COMPILER_LINTS) ; \
# cd .. ; \
# done
## This builds the nano_core binary itself, which is the fully-linked code that first runs right after the bootloader
$(nano_core_binary): cargo $(nano_core_static_lib) $(linker_script)
$(CROSS)ld -n -T $(linker_script) -o $(nano_core_binary) $(compiled_nano_core_asm) $(nano_core_static_lib)
## Fix up CLS sections.
cargo run --release --manifest-path $(ROOT_DIR)/tools/elf_cls/Cargo.toml -- $(ARCH) --file $(nano_core_binary)
## Dump readelf output for verification. See pull request #542 for more details:
## @RUSTFLAGS="" cargo run --release --manifest-path $(ROOT_DIR)/tools/demangle_readelf_file/Cargo.toml \
## <($(CROSS)readelf -s -W $(nano_core_binary) | sed '/OBJECT LOCAL .* str\./d;/NOTYPE LOCAL /d;/FILE LOCAL /d;/SECTION LOCAL /d;') \
## > $(ROOT_DIR)/readelf_output
## run "readelf" on the nano_core binary, remove irrelevant LOCAL symbols from the ELF file, demangle it, serialize it, and then output to a serde file
@RUSTFLAGS="" cargo run --release --manifest-path $(ROOT_DIR)/tools/serialize_nano_core/Cargo.toml \
<(RUSTFLAGS="" cargo run --release --manifest-path $(ROOT_DIR)/tools/demangle_readelf_file/Cargo.toml \
<($(CROSS)readelf -S -s -W $(nano_core_binary) \
| sed '/OBJECT LOCAL .* str\./d;/NOTYPE LOCAL /d;/FILE LOCAL /d;/SECTION LOCAL /d;')) \
> $(OBJECT_FILES_BUILD_DIR)/$(KERNEL_PREFIX)nano_core.serde
## `.sym`: this doesn't parse the object file at compile time, instead including the modified output of "readelf" as a boot module so it can then
## be parsed during boot. See pull request #542 for more details.
## @RUSTFLAGS="" cargo run --release --manifest-path $(ROOT_DIR)/tools/demangle_readelf_file/Cargo.toml \
## <($(CROSS)readelf -S -s -W $(nano_core_binary) | sed '/OBJECT LOCAL .* str\./d;/NOTYPE LOCAL /d;/FILE LOCAL /d;/SECTION LOCAL /d;') \
## > $(OBJECT_FILES_BUILD_DIR)/$(KERNEL_PREFIX)nano_core.sym
## @echo -n -e '\0' >> $(OBJECT_FILES_BUILD_DIR)/$(KERNEL_PREFIX)nano_core.sym
## `.bin`: this doesn't parse the object file at compile time, instead including the nano_core binary as a boot module so it can then be parsed during
## boot. See pull request #542 for more details.
## @cp $(nano_core_binary) $(OBJECT_FILES_BUILD_DIR)/$(KERNEL_PREFIX)nano_core.bin
### This target auto-generates a new grub.cfg file and uses grub to build a bootable ISO.
### This target should be invoked when all of contents of `ISOFILES` are ready to be packaged into an ISO.
grub:
@mkdir -p $(ISOFILES)/boot/grub
@RUSTFLAGS="" cargo run --release --manifest-path $(ROOT_DIR)/tools/grub_cfg_generation/Cargo.toml -- $(ISOFILES)/modules/ -o $(ISOFILES)/boot/grub/grub.cfg
@$(GRUB_MKRESCUE) -o $(iso) $(ISOFILES) 2> /dev/null
### This target uses limine to build a bootable ISO.
### This target should be invoked when all of contents of `ISOFILES` are ready to be packaged into an ISO.
limine:
@cd $(OBJECT_FILES_BUILD_DIR)/ && ls | cpio --no-absolute-filenames -o > $(ISOFILES)/modules.cpio
@RUSTFLAGS="" cargo run -r --manifest-path $(ROOT_DIR)/tools/limine_compress_modules/Cargo.toml -- -i $(ISOFILES)/modules.cpio -o $(ISOFILES)/modules.cpio.lz4
@rm $(ISOFILES)/modules.cpio
@cp cfg/limine.cfg $(LIMINE_DIR)/limine-cd.bin $(LIMINE_DIR)/limine-cd-efi.bin $(LIMINE_DIR)/limine.sys $(ISOFILES)/
@rm -f $(iso)
@xorriso -as mkisofs \
-b limine-cd.bin -no-emul-boot -boot-load-size 4 \
-boot-info-table --efi-boot limine-cd-efi.bin \
-efi-boot-part --efi-boot-image --protective-msdos-label \
$(ISOFILES)/ -o $(iso)
@$(MAKE) -C $(LIMINE_DIR)
@$(LIMINE_DIR)/limine-deploy $(iso)
## This downloads the OVMF EFI firmware, needed by QEMU to boot an EFI app.
##
## These binary files are built by Github user retrage at:
## https://github.com/retrage/edk2-nightly.
$(efi_firmware):
@echo -e "\033[1;34m\nDownloading prebuilt EFI firmware from GitHub...\033[0m"
@wget -nv --show-progress https://raw.githubusercontent.com/retrage/edk2-nightly/$(OVMF_COMMIT)/bin/$(OVMF_FILE) -O $(efi_firmware)
### This target copies all extra files into the `ISOFILES` directory,
### collapsing their directory structure into a single file name with `!` as the directory delimiter.
### The contents of the EXTRA_FILES directory will be available at runtime within Theseus's root fs, too.
### See the `README.md` in the `extra_files` directory for more info.
extra_files:
@mkdir -p $(OBJECT_FILES_BUILD_DIR)
@for f in $(shell cd $(EXTRA_FILES) && find * -type f); do \
ln -f $(EXTRA_FILES)/$${f} $(OBJECT_FILES_BUILD_DIR)/`echo -n $${f} | sed 's/\//!/g'` & \
done; wait
### Target for building tlibc, Theseus's libc.
### This should be run after `make iso` has completed.
### It builds a new .iso that includes tlibc, which can be run using `make orun`.
### Currently we can manually load tlibc within Theseus for testing purposes by running `ns --load path/to/tlibc_file`.
.PHONY: tlibc
TLIBC_OBJ_FILE := tlibc/target/$(TARGET)/$(BUILD_MODE)/tlibc.o
tlibc:
# $(MAKE) -C tlibc
( cd ./tlibc; sh build.sh )
@for f in $(TLIBC_OBJ_FILE); do \
$(CROSS)strip --strip-debug $${f} ; \
cp -vf $${f} $(OBJECT_FILES_BUILD_DIR)/`basename $${f} | sed -n -e 's/\(.*\)/$(APP_PREFIX)\1/p'` 2> /dev/null ; \
done
$(MAKE) bootloader=$(bootloader) $(bootloader)
@echo -e "\n\033[1;32m The build of tlibc finished successfully and was packaged into the Theseus ISO.\033[0m"
@echo -e " --> Use 'make orun' to run it now (don't use 'make run', that will overwrite tlibc)"
@echo -e " --> In Theseus, run 'ns --load /namespaces/_applications/tlibc.o' to load tlibc."
### Target for building a test C language executable.
### This should be run after `make iso` and then `make tlibc` have both completed.
.PHONY: c_test
# C_TEST_TARGET := dummy_works
C_TEST_TARGET := print_test
c_test:
$(MAKE) -C c_test $(C_TEST_TARGET)
@for f in c_test/$(C_TEST_TARGET); do \
$(CROSS)strip --strip-debug $${f} ; \
cp -vf $${f} $(OBJECT_FILES_BUILD_DIR)/`basename $${f} | sed -n -e 's/\(.*\)/$(EXECUTABLE_PREFIX)\1/p'` 2> /dev/null ; \
done
$(MAKE) bootloader=$(bootloader) $(bootloader)
@echo -e "\n\033[1;32m The build of $(C_TEST_TARGET) finished successfully and was packaged into the Theseus ISO.\033[0m"
@echo -e " --> Use 'make orun' to run it now (don't use 'make run')"
@echo -e " --> In Theseus, run 'loadc /namespaces/_executables/$(C_TEST_TARGET)' to load and run the C program."
### Demo/test target for building libtheseus
libtheseus: theseus_cargo $(ROOT_DIR)/libtheseus/Cargo.* $(ROOT_DIR)/libtheseus/src/*
@( \
cd $(ROOT_DIR)/libtheseus && \
$(THESEUS_CARGO_BIN) --input $(DEPS_BUILD_DIR) build; \
)
### This target builds the `theseus_cargo` tool as a dedicated binary.
theseus_cargo: $(wildcard $(THESEUS_CARGO)/Cargo.*) $(wildcard$(THESEUS_CARGO)/src/*)
@echo -e "\n=================== Building the theseus_cargo tool ==================="
cargo install --locked --force --path=$(THESEUS_CARGO) --root=$(THESEUS_CARGO)
### Removes the build directory and all compiled Rust objects.
clean:
@rm -rf $(BUILD_DIR)
cargo clean
### Removes only the old files that were copied into the build directory from a previous build.
### This is necessary to avoid lingering build files that aren't relevant to a new build,
### and would thus cause incremental re-builds to not work correctly.
### All other build files are left intact.
clean-old-build:
@rm -rf $(OBJECT_FILES_BUILD_DIR)
@rm -rf $(DEPS_BUILD_DIR)
@rm -rf $(DEBUG_SYMBOLS_DIR)
# ## (This is currently not used in Theseus, since we don't run anything in userspace)
# ## This builds all userspace programs
# userspace:
# @echo -e "\n======== BUILDING USERSPACE ========"
# @$(MAKE) -C old_crates/userspace all
# ## copy userspace binary files and add the __u_ prefix
# @mkdir -p $(ISOFILES)/modules
# @for f in `find $(ROOT_DIR)/old_crates/userspace/build -type f` ; do \
# cp -vf $${f} $(ISOFILES)/modules/`basename $${f} | sed -n -e 's/\(.*\)/__u_\1/p'` 2> /dev/null ; \
# done
## TODO FIXME: fix up the applications build procedure so we can use lints for them, such as disabling unsafe code.
# ## The directory where we store custom lints (compiler plugins)
# COMPILER_PLUGINS_DIR = $(ROOT_DIR)/compiler_plugins
# ## Applications are forbidden from using unsafe code
# COMPILER_LINTS += -D unsafe-code
# ## Applications must have a main function
# COMPILER_LINTS += --extern application_main_fn=$(COMPILER_PLUGINS_DIR)/target/$(BUILD_MODE)/libapplication_main_fn.so \
# -Z extra-plugins=application_main_fn \
# -D application_main_fn
#
# ## Builds our custom lints in the compiler plugins directory so we can use them here
# compiler_plugins:
# @cd $(COMPILER_PLUGINS_DIR) && cargo build $(CARGOFLAGS)
## This is a special target that enables SIMD personalities.
## It builds everything with the SIMD-enabled x86_64-unknown-theseus-sse target,
## and then builds everything again with the regular x86_64-unknown-theseus target.
## The "normal" target must come last ('build_sse', THEN the regular 'build') to ensure that the final nano_core_binary is non-SIMD.
simd_personality_sse : export TARGET := x86_64-unknown-theseus
simd_personality_sse : export BUILD_MODE = release
simd_personality_sse : export override THESEUS_CONFIG += simd_personality simd_personality_sse
simd_personality_sse: clean-old-build build_sse build
## after building all the modules, copy the kernel boot image files
@echo -e "********* AT THE END OF SIMD_BUILD: TARGET = $(TARGET), KERNEL_PREFIX = $(KERNEL_PREFIX), APP_PREFIX = $(APP_PREFIX)"
$(MAKE) bootloader=$(bootloader) copy_kernel $(bootloader)
## run it in QEMU
$(QEMU_BIN) $(QEMU_FLAGS)
## This target is like "simd_personality_sse", but uses AVX instead of SSE.
## It builds everything with the SIMD-enabled x86_64-unknown-theseus-avx target,
## and then builds everything again with the regular x86_64-unknown-theseus target.
## The "normal" target must come last ('build_avx', THEN the regular 'build') to ensure that the final nano_core_binary is non-SIMD.
simd_personality_avx : export TARGET := x86_64-unknown-theseus
simd_personality_avx : export BUILD_MODE = release
simd_personality_avx : export override THESEUS_CONFIG += simd_personality simd_personality_avx
simd_personality_avx : export override CFLAGS += -DENABLE_AVX
simd_personality_avx: clean-old-build build_avx build
## after building all the modules, copy the kernel boot image files
@echo -e "********* AT THE END OF SIMD_BUILD: TARGET = $(TARGET), KERNEL_PREFIX = $(KERNEL_PREFIX), APP_PREFIX = $(APP_PREFIX)"
$(MAKE) bootloader=$(bootloader) copy_kernel $(bootloader)
## run it in QEMU
$(QEMU_BIN) $(QEMU_FLAGS)
### build_sse builds the kernel and applications with the x86_64-unknown-theseus-sse target.
### It can serve as part of the simd_personality_sse target.
build_sse : export override TARGET := x86_64-unknown-theseus-sse
build_sse : export override RUSTFLAGS += -C no-vectorize-loops
build_sse : export override RUSTFLAGS += -C no-vectorize-slp
build_sse : export KERNEL_PREFIX := ksse\#
build_sse : export APP_PREFIX := asse\#
build_sse:
$(MAKE) build
### build_avx builds the kernel and applications with the x86_64-unknown-theseus-avx target.
### It can serve as part of the simd_personality_avx target.
build_avx : export override TARGET := x86_64-unknown-theseus-avx
build_avx : export override RUSTFLAGS += -C no-vectorize-loops
build_avx : export override RUSTFLAGS += -C no-vectorize-slp
build_avx : export KERNEL_PREFIX := kavx\#
build_avx : export APP_PREFIX := aavx\#
build_avx:
$(MAKE) build
### build_server is a target that builds Theseus into a regular ISO
### and then sets up an HTTP server that provides module object files
### for a running instance of Theseus to download for OTA live updates.
build_server: preserve_old_modules iso
OLD_MODULES_DIR=$(OBJECT_FILES_BUILD_DIR)_old \
NEW_MODULES_DIR=$(OBJECT_FILES_BUILD_DIR) \
NEW_DIR_NAME=$(UPDATE_DIR) \
bash scripts/build_server.sh
preserve_old_modules:
@mv $(OBJECT_FILES_BUILD_DIR) $(OBJECT_FILES_BUILD_DIR)_old
cargo clean
###################################################################################################
########################### Targets for clippy and documentation ##################################
###################################################################################################
## Runs clippy on a full build of Theseus, with all crates included.
## Note that this does not cover all combinations of features or cfg values.
##
## We allow building with THESEUS_CONFIG options, but not with any other RUSTFLAGS,
## because the default RUSTFLAGS used to build Theseus aren't compatible with clippy.
ifeq ($(ARCH),x86_64)
clippy : export override FEATURES += --features theseus_features/everything
else ifeq ($(ARCH),aarch64)
clippy : export override FEATURES := $(subst --workspace,,$(FEATURES))
endif
clippy : export override RUSTFLAGS = $(patsubst %,--cfg %, $(THESEUS_CONFIG))
clippy:
RUST_TARGET_PATH='$(CFG_DIR)' RUSTFLAGS='$(RUSTFLAGS)' \
cargo clippy \
$(BUILD_STD_CARGOFLAGS) $(FEATURES) \
--target $(TARGET) \
-- -D clippy::all
## The output directory for source-level documentation.
RUSTDOC_OUT := $(BUILD_DIR)/doc
RUSTDOC_OUT_FILE := $(RUSTDOC_OUT)/___Theseus_Crates___/index.html
## Builds Theseus's source-level documentation for all Rust crates except applications.
## The entire project is built as normal using the `cargo doc` command (`rustdoc` under the hood).
docs: doc
doc : export override RUSTDOCFLAGS += -A rustdoc::private_intra_doc_links
doc : export override RUSTFLAGS=
doc : export override CARGOFLAGS=
doc:
## Build the docs for select library crates, namely those not hosted online.
## We do this first such that the main `cargo doc` invocation below can see and link to them.
@cargo doc --no-deps \
--package atomic_linked_list \
--package cow_arc \
--package debugit \
--package dereffer \
--package dfqueue \
--package irq_safety \
--package keycodes_ascii \
--package lockable \
--package locked_idt \
--package mouse_data \
--package owned_borrowed_trait \
--package percent-encoding \
--package port_io \
--package range_inclusive \
--package stdio \
--package str_ref
## Now, build the docs for all of Theseus's main kernel crates.
@cargo doc --workspace --no-deps $(addprefix --exclude , $(APP_CRATE_NAMES)) --features nano_core/bios
@rustdoc --output target/doc --crate-name "___Theseus_Crates___" $(ROOT_DIR)/kernel/_doc_root.rs
@rm -rf $(RUSTDOC_OUT)
@mkdir -p $(RUSTDOC_OUT)
@cp -rf target/doc/. $(RUSTDOC_OUT)
@echo -e "\nTheseus source docs are now available at: \"$(RUSTDOC_OUT_FILE)\"."
## Opens the documentation root in the system's default browser.
## the "powershell" command is used on Windows Subsystem for Linux
view-docs: view-doc
view-doc: doc
@echo -e "Opening documentation index file in your browser..."
ifneq ($(IS_WSL), )
wslview "$(shell realpath --relative-to="$(ROOT_DIR)" "$(RUSTDOC_OUT_FILE)")" &
else
@xdg-open $(RUSTDOC_OUT_FILE) > /dev/null 2>&1 || open $(RUSTDOC_OUT_FILE) &
endif
### The locations of Theseus's book-style documentation.
BOOK_SRC := $(ROOT_DIR)/book
BOOK_OUT := $(BUILD_DIR)/book
BOOK_OUT_FILE := $(BOOK_OUT)/html/index.html
### Builds the Theseus book-style documentation using `mdbook`.
book: $(wildcard $(BOOK_SRC)/src/*) $(BOOK_SRC)/book.toml
ifneq ($(shell mdbook --version > /dev/null 2>&1 && echo $$?), 0)
@echo -e "\nError: please install mdbook:"
@echo -e " cargo +stable install mdbook --force"
@echo -e "You can optionally install linkcheck too:"
@echo -e " cargo +stable install mdbook-linkcheck --force"
@exit 1
endif
@mdbook build $(MDBOOK_ARGS) $(BOOK_SRC) -d $(BOOK_OUT)
@echo -e "\nThe Theseus Book is now available at \"$(BOOK_OUT_FILE)\"."
### Opens the Theseus book.
export override MDBOOK_ARGS+=--open
view-book: book
@echo -e "Opened the Theseus book in your browser."
### Removes all built documentation
clean-doc:
@cargo clean --doc
@rm -rf $(RUSTDOC_OUT) $(BOOK_OUT)
### The primary documentation for this makefile itself.
help:
@echo -e "\nThe following make targets are available:"
@echo -e " iso:"
@echo -e "\t The default and most basic target. Builds Theseus OS with the default feature set and creates a bootable ISO image."
@echo -e " all:"
@echo -e " full:"
@echo -e "\t Same as 'iso', but builds all Theseus OS crates by enabling the 'theseus_features/everything' feature."
@echo -e " run:"
@echo -e "\t Builds Theseus (via the 'iso' target) and runs it using QEMU."
@echo -e " run_pause:"
@echo -e "\t Same as 'run', but pauses QEMU at its GDB stub entry point,"
@echo -e "\t which waits for you to connect a GDB debugger using 'make gdb'."
@echo -e " orun:"
@echo -e "\t Runs the existing build of Theseus using QEMU, without building Theseus first."
@echo -e " orun_pause:"
@echo -e "\t Same as 'orun', but pauses QEMU at its GDB stub entry point,"
@echo -e "\t which waits for you to connect a GDB debugger using 'make gdb'."
@echo -e " loadable:"
@echo -e "\t Same as 'run', but enables the 'loadable' configuration so that all crates are dynamically loaded."
@echo -e " wasmtime:"
@echo -e "\t Same as 'run', but includes the 'wasmtime' crates in the build."
@echo -e " gdb:"
@echo -e "\t Runs a new instance of GDB that connects to an already-running x86_64 QEMU instance."
@echo -e "\t You must run an instance of Theseus on x86_64 in QEMU beforehand in a separate terminal."
@echo -e " gdb_aarch64:"
@echo -e "\t Runs a new instance of GDB multiarch that connects to an already-running aarch64 QEMU instance."
@echo -e "\t You must run an instance of Theseus on aarch64 in QEMU beforehand in a separate terminal."
@echo -e " bochs:"
@echo -e "\t Same as 'make run', but runs Theseus in the Bochs emulator instead of QEMU."
@echo -e " usb:"
@echo -e "\t Builds Theseus as a bootable .iso and writes it to the specified USB drive."
@echo -e "\t The USB drive is specified as drive=<dev-name>, e.g., 'make usb drive=sdc',"
@echo -e "\t in which the USB drive is connected as /dev/sdc. This target requires sudo."
@echo -e " pxe:"
@echo -e "\t Builds Theseus as a bootable .iso and copies it to the tftpboot folder for network booting over PXE."
@echo -e "\t You can specify a new network device with netdev=<interface-name>, e.g., 'make pxe netdev=eth0'."
@echo -e "\t You can also specify the IP address with 'ip=<addr>'. This target requires sudo."
@echo -e " simd_personality_[sse|avx]:"
@echo -e "\t Builds Theseus with a regular personality and a SIMD-enabled personality (either SSE or AVX),"
@echo -e "\t then runs it just like the 'make run' target."
@echo -e " build_server:"
@echo -e "\t Builds Theseus (as with the 'iso' target) and then runs a build server hosted on this machine"
@echo -e "\t that can be used for over-the-air live evolution."
@echo -e "\t You can specify the name of the directory of newly-built modules by setting the 'UPDATE_DIR' environment variable."
@echo -e "\t This target should be invoked as an incremental build after a prior build has already completed."
@echo -e "\t For example, first checkout version 1 (e.g., a specific git commit), build it as normal,"
@echo -e "\t then checkout version 2 (or otherwise make some changes) and run 'make build_server'."
@echo -e "\t Then, a running instance of Theseus version 1 can contact this machine's build_server to update itself to version 2."
@echo -e "\nThe following key-value options are available to select a bootloader:"
@echo -e " bootloader=grub|limine"
@echo -e "\t Configure which bootloader to pack into the final \".iso\" file."
@echo -e "\t 'grub': Use the GRUB bootloader. Default value."
@echo -e "\t 'limine': Use the Limine bootloader. See setup instructions in the README."
@echo -e "\nThe following key-value options are available to customize the build process:"
@echo -e " merge_sections=yes|no"
@echo -e "\t Choose whether sections in crate object files are merged together."
@echo -e "\t This *significantly* improves crate load times and reduces memory usage,"
@echo -e "\t though it may present problems for crate swapping for evolution and fault recovery."
@echo -e "\t This is strictly a post-compilation action, it doesn't affect how code is compiled."
@echo -e " debug=full|base|none"
@echo -e "\t Configure which debug symbols are stripped from the build artifacts."
@echo -e "\t Stripped symbols are placed into files ending with \".dbg\" in \"$(DEBUG_SYMBOLS_DIR)\"."
@echo -e "\t This is strictly a post-compilation action, it doesn't affect how code is compiled."
@echo -e "\t 'full': Keep debug symbols in all files, including the base kernel image and all crate object files."
@echo -e "\t 'base': Keep debug symbols in only the base kernel image; strip debug symbols from crate object files."
@echo -e "\t 'none': Strip debug symbols from both the base kernel image and all crate object files."
@echo -e "\t This is the default option, because it is the fastest to boot."
@echo -e "\nThe following key-value options are available for QEMU targets, like 'run':"
@echo -e " net=user|tap|none"
@echo -e "\t Configure networking in the QEMU guest:"
@echo -e "\t 'user': Enable networking with an e1000 NIC in the guest and a userspace SLIRP-based interface in the host (QEMU default)."
@echo -e "\t 'tap' : Enable networking with an e1000 NIC in the guest and a TAP interface in the host."
@echo -e "\t 'none': Disable all networking in the QEMU guest. This is the default behavior if no other 'net' option is provided."
# @echo -e " kvm=yes:"
# @echo -e "\t Enable KVM acceleration (the host computer must support it)."
@echo -e " host=yes"
@echo -e "\t Enable KVM and use the host CPU model. This is required for using certain x86 hardware not supported by QEMU, e.g., PMU, AVX."
@echo -e " int=yes"
@echo -e "\t Enable interrupt logging in QEMU console (-d int). This is VERY verbose and slow."
@echo -e " vfio=<PCI_DEVICE_SLOT>"
@echo -e "\t Use VFIO-based PCI device assignment (passthrough) in QEMU for the given device slot, e.g 'vfio=59:00.0'"
@echo -e " SERIAL<N>=<BACKEND>"
@echo -e "\t Connect a guest OS serial port (e.g., 'SERIAL1' or 'SERIAL2') to a QEMU-supported backend."
@echo -e "\t For example, 'SERIAL2=pty' will connect the second serial port for the given architecture"
@echo -e "\t ('COM2 on x86) to a newly-allocated pseudo-terminal on Linux, e.g., '/dev/pts/6'."
@echo -e "\t For the 'pty' option, QEMU will print a statement like so:"
@echo -e "\t char device redirected to /dev/pts/6 (label serial1)"
@echo -e "\t Note that QEMU uses 0-based indexing for serial ports, so its 'serial1' label refers to the second serial port, our 'SERIAL2'."
@echo -e "\t You can then connect to this using something like 'screen /dev/pts/6' or 'picocom /dev/pts/6',"
@echo -e "\t or use the below 'terminal=' option to auto-launch a new terminal."
@echo -e "\t Other options include 'stdio' (the default for 'SERIAL1'), 'file', 'pipe', etc."
@echo -e "\t For more details, search the QEMU manual for '-serial dev'."
@echo -e " terminal=\"TERMINAL_COMMAND\""
@echo -e "\t Auto-launch a new terminal window connected to the specified SERIAL<N> TTY/PTY backend"
@echo -e "\t that QEMU created for us, as described above."
@echo -e "\t The TERMINAL_COMMAND is specific to your system's terminal emulator and available binaries,"
@echo -e "\t and will be invoked by our makefile with one argument: the PTY device file created by QEMU."
@echo -e "\t For example, on a default GNOME-based Linux distro with 'screen' installed, you can run:"
@echo -e "\t make run terminal=\"gnome-terminal -- screen\""
@echo -e "\t On a system with 'alacritty' installed, you can just run:"
@echo -e "\t make run terminal=alacritty"
@echo -e "\t The specific syntax of TERMINAL_COMMAND depends on your host system and chosen terminal emulator."
@echo -e " graphic=no"
@echo -e "\t Disable the graphical QEMU window, which reroutes the VGA text mode output to stdio."
@echo -e "\t -- Note: the VGA device will still exist and be used by Theseus, it just will not be displayed."
@echo -e "\nThe following make targets exist for building documentation:"
@echo -e " doc:"
@echo -e "\t Builds Theseus documentation from its Rust source code (rustdoc)."
@echo -e " view-doc:"
@echo -e "\t Builds Theseus documentation and then opens it in your default browser."
@echo -e " book:"
@echo -e "\t Builds the Theseus book using the mdbook Markdown tool."
@echo -e " view-book:"
@echo -e "\t Builds the Theseus book and then opens it in your default browser."
@echo -e "\t If the book doesn't open in your browser, install the latest version of mdbook."
@echo -e " clean-doc:"
@echo -e "\t Remove all generated documentation files."
@echo ""
###################################################################################################
##################### This section has QEMU arguments and configuration ###########################
###################################################################################################
QEMU_FLAGS ?=
QEMU_EXTRA ?=
SERIAL1 ?= stdio
SERIAL2 ?= pty
ifdef IOMMU
## Currently only the `q35` machine model supports a virtual IOMMU: <https://wiki.qemu.org/Features/VT-d>
QEMU_FLAGS += -machine q35,kernel-irqchip=split
QEMU_FLAGS += -device intel-iommu,intremap=on,caching-mode=on
endif
## Boot from the cd-rom drive
ifeq ($(boot_spec), bios)
QEMU_FLAGS += -cdrom $(iso) -boot d
else ifeq ($(boot_spec), uefi)
## We use `-bios` instead of `-pflash` because `-pflash` requires the file to be exactly 64MB.
## See:
## - https://wiki.qemu.org/Features/PC_System_Flash
## - https://github.com/tianocore/edk2/blob/316e6df/OvmfPkg/README#L68
QEMU_FLAGS += -bios $(efi_firmware)
QEMU_FLAGS += -drive format=raw,file=$(iso)
endif
## Don't reboot or shutdown upon failure or a triple reset
QEMU_FLAGS += -no-reboot -no-shutdown
## Enable a GDB stub so we can connect GDB to the QEMU instance
QEMU_FLAGS += -s
## Enable the first serial port (the default log) to be redirected to the host terminal's stdio.
## Optionally, use the below `mon:` prefix to have the host terminal forward escape/control sequences to this serial port.
# QEMU_FLAGS += -serial $(SERIAL1)
QEMU_FLAGS += -serial mon:$(SERIAL1)
## Attach a second serial port to QEMU, which can be used for a separate headless shell/terminal.
## For example, if this is `pty`, and QEMU chooses to allocate a new pseudo-terminal at /dev/pts/6,
## then you can connect to this serial port by running a tty connector application in a new window:
## -- `screen /dev/pts/6`
## -- `picocom /dev/pts/6`
QEMU_FLAGS += -serial mon:$(SERIAL2)
## Disable the graphical display (for running in "headless" mode)
## `-vga none`: removes the VGA card
## `-display none`: disables QEMU's graphical display
## `-nographic`: disables QEMU's graphical display and redirects VGA text mode output to serial.
ifeq ($(graphic), no)
QEMU_FLAGS += -nographic
endif
## Set the amount of system memory (RAM) provided to the QEMU guest OS
QEMU_MEMORY ?= 512M
QEMU_FLAGS += -m $(QEMU_MEMORY)
## Enable multicore CPUs, i.e., SMP (Symmetric Multi-Processor)
QEMU_CPUS ?= 4
QEMU_FLAGS += -smp $(QEMU_CPUS)
## Add a disk drive, a PATA drive over an IDE controller interface.
## Currently this is only supported on x86_64.
DISK_IMAGE ?= fat32.img
ifeq ($(ARCH),x86_64)
ifneq ($(wildcard $(DISK_IMAGE)),)
QEMU_FLAGS += -drive format=raw,file=fat32.img,if=ide
endif
endif
## We don't yet support SATA in Theseus, but this is how to add a SATA drive over the AHCI interface.
# QEMU_FLAGS += -drive id=my_disk,file=$(DISK_IMAGE),if=none -device ahci,id=ahci -device ide-drive,drive=my_disk,bus=ahci.0
## QEMU's OUI dictates that the MAC addr start with "52:54:00:"
MAC_ADDR ?= 52:54:00:d1:55:01
## Read about QEMU networking options here: https://www.qemu.org/2018/05/31/nic-parameter/
ifeq ($(net),user)
## user-based networking setup with standard e1000 ethernet NIC
QEMU_FLAGS += -device e1000,netdev=network0,mac=$(MAC_ADDR) -netdev user,id=network0
## Dump network activity to a pcap file
QEMU_FLAGS += -object filter-dump,id=f1,netdev=network0,file=netdump.pcap
else ifeq ($(net),tap)
## TAP-based networking setup with a standard e1000 ethernet NIC frontent (in the guest) and the TAP backend (in the host)
QEMU_FLAGS += -device e1000,netdev=network0,mac=$(MAC_ADDR) -netdev tap,id=network0,ifname=tap0,script=no,downscript=no
## Dump network activity to a pcap file
QEMU_FLAGS += -object filter-dump,id=f1,netdev=network0,file=netdump.pcap
else ifeq ($(net),none)
QEMU_FLAGS += -net none
else ifneq (,$(net))
$(error Error: unsupported option "net=$(net)")
endif
## Dump interrupts to the serial port log
ifeq ($(int),yes)
QEMU_FLAGS += -d int
endif
ifeq ($(host),yes)
## KVM acceleration is required when using the host cpu model
QEMU_FLAGS += -cpu host -accel kvm
else ifeq ($(ARCH),aarch64)
QEMU_FLAGS += -machine virt,gic-version=3
QEMU_FLAGS += -device ramfb
QEMU_FLAGS += -cpu cortex-a72
QEMU_FLAGS += -usb
QEMU_FLAGS += -device usb-ehci,id=ehci
QEMU_FLAGS += -device usb-kbd
else
QEMU_FLAGS += -cpu Broadwell
endif
## Currently, kvm by itself can cause problems, but it works with the "host" option (above).
ifeq ($(kvm),yes)
$(error Error: the 'kvm=yes' option is currently broken. Use 'host=yes' instead")
# QEMU_FLAGS += -accel kvm
endif
## Enable passthrough of a PCI device in QEMU by passing its slot information to VFIO.
## Slot information is its bus, device, and function number assigned by the host OS, e.g., 'vfio=59:00.0'.
ifdef vfio
QEMU_FLAGS += -device vfio-pci,host=$(vfio)
endif
QEMU_FLAGS += $(QEMU_EXTRA)
###################################################################################################
########################## Targets for running and debugging Theseus ##############################
###################################################################################################
### `qemu`/`orun` (old run): runs the most recent build without rebuilding.
### This is the base-level target responsible for actually invoking QEMU;
### all other targets that want to invoke QEMU should depend on this target to do so.
qemu: orun
orun:
ifdef terminal
## Check which PTY/TTY the OS would give to the next process that requests one,
## which is the best way to guess which PTY QEMU will use for redirected serial I/O.
$(eval temp_tty += $(shell cargo run --release --quiet --manifest-path $(ROOT_DIR)/tools/get_tty/Cargo.toml))
## If another process obtains that TTY here before we can run QEMU,
## the 'terminal' command below will connect to the wrong TTY, but there's nothing we can do.
##
## Sleep for 2 seconds to allow QEMU enough time to start and request the TTY.
(sleep 2 && $(terminal) $(temp_tty)) & $(QEMU_BIN) $(QEMU_FLAGS)
else
$(QEMU_BIN) $(QEMU_FLAGS)
endif
### Old Run Pause: runs the most recent build without rebuilding, but pauses QEMU until GDB is connected.
orun_pause : export override QEMU_FLAGS += -S
orun_pause: orun