Skip to content

Commit f19df56

Browse files
committed
Add description about dynamic linking to README
Since the dynamic linking was introduced in the previous commit, this commit updates the README to describe how to use dynamic linking mode and provides basic usage examples for illustration.
1 parent 9bc507e commit f19df56

File tree

1 file changed

+36
-3
lines changed

1 file changed

+36
-3
lines changed

README.md

Lines changed: 36 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,10 +74,16 @@ To execute the snapshot test, install the packages below:
7474
$ sudo apt-get install graphviz jq
7575
```
7676

77+
Additionally, because `shecc` supports the dynamic linking mode for the Arm architecture,
78+
it needs to install the ARM GNU toolchain to obtain the ELF interpreter and other dependencies:
79+
```shell
80+
$ sudo apt-get install gcc-arm-linux-gnueabihf
81+
```
82+
7783
## Build and Verify
7884

7985
Configure which backend you want, `shecc` supports ARMv7-A and RV32IM backend:
80-
```
86+
```shell
8187
$ make config ARCH=arm
8288
# Target machine code switch to Arm
8389

@@ -86,13 +92,29 @@ $ make config ARCH=riscv
8692
```
8793

8894
Run `make` and you should see this:
95+
```shell
96+
$ make
97+
CC+LD out/inliner
98+
GEN out/libc.inc
99+
CC out/src/main.o
100+
LD out/shecc
101+
SHECC out/shecc-stage1.elf
102+
SHECC out/shecc-stage2.elf
89103
```
104+
105+
Run `make LINK_MODE=dynamic` to use the dynamic linking mode and generate the dynamically linked compiler:
106+
```shell
107+
# If using the dynamic linking mode, you should add 'LINK_MODE=dynamic' for each 'make' command.
108+
$ make LINK_MODE=dynamic
90109
CC+LD out/inliner
91110
GEN out/libc.inc
92111
CC out/src/main.o
93112
LD out/shecc
94113
SHECC out/shecc-stage1.elf
95114
SHECC out/shecc-stage2.elf
115+
116+
$ file out/shecc-stage2.elf
117+
out/shecc-stage2.elf: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, not stripped
96118
```
97119

98120
For development builds with memory safety checks:
@@ -103,22 +125,32 @@ $ make check-sanitizer
103125

104126
File `out/shecc` is the first stage compiler. Its usage:
105127
```shell
106-
$ shecc [-o output] [+m] [--no-libc] [--dump-ir] <infile.c>
128+
$ shecc [-o output] [+m] [--no-libc] [--dump-ir] [--dynlink] <infile.c>
107129
```
108130

109131
Compiler options:
110132
- `-o` : Specify output file name (default: `out.elf`)
111133
- `+m` : Use hardware multiplication/division instructions (default: disabled)
112134
- `--no-libc` : Exclude embedded C library (default: embedded)
113135
- `--dump-ir` : Dump intermediate representation (IR)
136+
- `--dynlink` : Use dynamic linking (default: disabled)
114137

115-
Example:
138+
Example 1: static linking mode
116139
```shell
117140
$ out/shecc -o fib tests/fib.c
118141
$ chmod +x fib
119142
$ qemu-arm fib
120143
```
121144

145+
Example 2: dynamic linking mode
146+
147+
Notice that `/usr/arm-linux-gnueabihf` is the ELF interpreter prefix. Since the path may be different if you manually install the ARM GNU toolchain instead of using `apt-get`, you should set the prefix to the actual path.
148+
```shell
149+
$ out/shecc --dynlink -o fib tests/fib.c
150+
$ chmod +x fib
151+
$ qemu-arm -L /usr/arm-linux-gnueabihf fib
152+
```
153+
122154
### IR Regression Tests
123155

124156
To ensure the consistency of frontend (lexer, parser) behavior when working on it, the snapshot test is introduced.
@@ -142,6 +174,7 @@ use `update-snapshot` / `check-snapshot` instead.
142174

143175
`shecc` comes with a comprehensive test suite (200+ test cases). To run the tests:
144176
```shell
177+
# Add 'LINK_MODE=dynamic' if using the dynamic linking mode.
145178
$ make check # Run all tests (stage 0 and stage 2)
146179
$ make check-stage0 # Test stage 0 compiler only
147180
$ make check-stage2 # Test stage 2 compiler only

0 commit comments

Comments
 (0)