Skip to content

Commit 2043b9d

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 08e6325 commit 2043b9d

File tree

1 file changed

+39
-3
lines changed

1 file changed

+39
-3
lines changed

README.md

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,10 +74,19 @@ 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+
Another approach is to manually download and install the toolchain from [ARM Developer website](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
83+
84+
Select "x86_64 Linux hosted cross toolchains" - "AArch32 GNU/Linux target with hard float (arm-none-linux-gnueabihf)" to download the toolchain.
85+
7786
## Build and Verify
7887

7988
Configure which backend you want, `shecc` supports ARMv7-A and RV32IM backend:
80-
```
89+
```shell
8190
$ make config ARCH=arm
8291
# Target machine code switch to Arm
8392

@@ -86,13 +95,29 @@ $ make config ARCH=riscv
8695
```
8796

8897
Run `make` and you should see this:
98+
```shell
99+
$ make
100+
CC+LD out/inliner
101+
GEN out/libc.inc
102+
CC out/src/main.o
103+
LD out/shecc
104+
SHECC out/shecc-stage1.elf
105+
SHECC out/shecc-stage2.elf
89106
```
107+
108+
Run `make LINK_MODE=dynamic` to use the dynamic linking mode and generate the dynamically linked compiler:
109+
```shell
110+
# If using the dynamic linking mode, you should add 'LINK_MODE=dynamic' for each 'make' command.
111+
$ make LINK_MODE=dynamic
90112
CC+LD out/inliner
91113
GEN out/libc.inc
92114
CC out/src/main.o
93115
LD out/shecc
94116
SHECC out/shecc-stage1.elf
95117
SHECC out/shecc-stage2.elf
118+
119+
$ file out/shecc-stage2.elf
120+
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
96121
```
97122

98123
For development builds with memory safety checks:
@@ -103,22 +128,32 @@ $ make check-sanitizer
103128

104129
File `out/shecc` is the first stage compiler. Its usage:
105130
```shell
106-
$ shecc [-o output] [+m] [--no-libc] [--dump-ir] <infile.c>
131+
$ shecc [-o output] [+m] [--no-libc] [--dump-ir] [--dynlink] <infile.c>
107132
```
108133

109134
Compiler options:
110135
- `-o` : Specify output file name (default: `out.elf`)
111136
- `+m` : Use hardware multiplication/division instructions (default: disabled)
112137
- `--no-libc` : Exclude embedded C library (default: embedded)
113138
- `--dump-ir` : Dump intermediate representation (IR)
139+
- `--dynlink` : Use dynamic linking (default: disabled)
114140

115-
Example:
141+
Example 1: static linking mode
116142
```shell
117143
$ out/shecc -o fib tests/fib.c
118144
$ chmod +x fib
119145
$ qemu-arm fib
120146
```
121147

148+
Example 2: dynamic linking mode
149+
150+
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.
151+
```shell
152+
$ out/shecc --dynlink -o fib tests/fib.c
153+
$ chmod +x fib
154+
$ qemu-arm -L /usr/arm-linux-gnueabihf fib
155+
```
156+
122157
### IR Regression Tests
123158

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

143178
`shecc` comes with a comprehensive test suite (200+ test cases). To run the tests:
144179
```shell
180+
# Add 'LINK_MODE=dynamic' if using the dynamic linking mode.
145181
$ make check # Run all tests (stage 0 and stage 2)
146182
$ make check-stage0 # Test stage 0 compiler only
147183
$ make check-stage2 # Test stage 2 compiler only

0 commit comments

Comments
 (0)