Skip to content

Commit 5cb809c

Browse files
committed
update README to match paths and unikernel.nix changes
1 parent 86c6f06 commit 5cb809c

File tree

1 file changed

+14
-12
lines changed

1 file changed

+14
-12
lines changed

README.md

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -81,30 +81,32 @@ It's not always practical to rebuild the whole kernel during development. You ca
8181
$ nix-shell ./develop.nix
8282
```
8383

84-
From here, you will be put in a shell suited for development. If your editor has LSP support with clangd (e.g. neovim, emacs, VSCode, Zed), you will get proper goto-declarations and warnings. You can quickly rebuild the kernel library from here with `cmake -B build && (cd build; make)`, with all build dependencies handled by the shell. You can also build and run a unikernel from the shell with this oneliner: `(cd ./example && cmake -B build && (cd build && make) && boot ./build/hello_includeos.elf.bin)` after building IncludeOS. It might be convenient to use one terminal (or tab) for your editor, a second for building IncludeOS, and a third for building a unikernel.
84+
From here, you will be put in a shell suited for development. If your editor has LSP support with clangd (e.g. neovim, emacs, VSCode, Zed), you will get proper goto-declarations and warnings. You can quickly rebuild the kernel library from here with `cmake -B build && cmake --build build`, with all build dependencies handled by the shell.
85+
86+
You can also build and run a unikernel from the shell with this oneliner: `nix-build unikernel.nix && boot ./result/hello_includeos.elf.bin)` after building IncludeOS. It might be convenient to use one terminal (or tab) for your editor, a second for building IncludeOS, and a third for building a unikernel.
8587

8688
In summary:
8789
```bash
8890
~/repos/IncludeOS $ nix-shell ./develop.nix
89-
[nix-shell:~/repos/IncludeOS]$ cmake -B build && (cd build; make) # rebuilds IncludeOS
90-
[nix-shell:~/repos/IncludeOS]$ cd example
91-
[nix-shell:~/repos/IncludeOS/example]$ cmake -B build && (cd build; make) # rebuilds a bootable unikernel
92-
[nix-shell:~/repos/IncludeOS/example]$ boot ./build/hello_includeos.elf.bin # runs the unikernel image with qemu through vmrunner
91+
[nix-shell:~/repos/IncludeOS]$ cmake -B build && cmake --build build # rebuilds IncludeOS
92+
[nix-shell:~/repos/IncludeOS]$ nix-build ./unikernel.nix # rebuilds the example unikernel
93+
[nix-shell:~/repos/IncludeOS]$ boot ./result/hello_includeos.elf.bin # runs the unikernel image with qemu through vmrunner
9394
```
9495

9596
Alternatively, you may want to use `nix-shell` by itself (or nested inside the development shell), which handles both building the unikernel found under `./example/` and puts you in a convenient shell for testing out a unikernel.
9697

9798
```bash
98-
~/repos/IncludeOS $ nix-shell --run 'boot hello_includeos.elf.bin'
99+
# both these require vmrunner's booth on path
100+
~/repos/IncludeOS $ nix-shell unikernel.nix --run 'boot hello_includeos.elf.bin'
99101
# or
100-
~/repos/IncludeOS $ nix-shell # updating IncludeOS after entering this shell won't rebuild the os library automatically!
101-
[nix-shell:~/repos/IncludeOS]$ boot hello_includeos.elf.bin
102+
~/repos/IncludeOS $ nix-shell unikernel.nix
103+
[nix-shell:~/repos/IncludeOS/result]$ boot hello_includeos.elf.bin
102104
```
103105

104106
If you want to build a different unikernel than the example, this can be specified with the `--argstr unikernel [path]` parameter. This is primarily used for integration tests. For example, to build and run the stacktrace-test:
105107

106108
```bash
107-
$ nix-shell --argstr unikernel ./test/kernel/integration/stacktrace
109+
$ nix-build unikernel.nix --argstr unikernel ./test/integration/kernel/stacktrace --doCheck true
108110
[...]
109111
nix$ ls -l kernel*
110112
kernel_stacktrace
@@ -122,14 +124,14 @@ We reached the end.
122124
To build and run the test VM as a single command:
123125

124126
```bash
125-
$ nix-shell --argstr unikernel ./test/kernel/integration/stacktrace --run ./test.py
127+
$ nix-build unikernel.nix --argstr unikernel ./test/integration/kernel/stacktrace --doCheck true
126128
```
127129

128130
### <a name="running_tests"></a> Running tests
129131

130-
You can run all the integration tests using the script `./test.sh`. The tests will run locally in the nix environment. We recommend manually verifying that all the tests pass locally before submitting a new PR to IncludeOS to save review time.
132+
You can run all the integration tests using the script `./test/test.sh`. The tests will run locally in the nix environment. We recommend manually verifying that all the tests pass locally before submitting a new PR to IncludeOS to save review time.
131133

132-
Individual tests can be run with `nix-shell` directly. See `test.sh` for more details.
134+
Most individual tests can be run with `nix-build` directly, while some require `nix-shell` due to sandboxing constraints. See `./test/test.sh` for more details.
133135

134136
## <a name="contribute"></a> Contributing to IncludeOS
135137

0 commit comments

Comments
 (0)