Skip to content

Commit 2e54fbf

Browse files
committed
[GR-54633] Update Native Image static linking guide.
PullRequest: graal/18253
2 parents b1b07b9 + 1dd1862 commit 2e54fbf

File tree

1 file changed

+13
-9
lines changed

1 file changed

+13
-9
lines changed

docs/reference-manual/native-image/guides/build-static-and-mostly-static-executable.md

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,14 @@ GraalVM Native Image by default builds dynamically linked binaries: at build tim
1212

1313
However, you can create a statically linked or mostly-statically linked native executable, depending on your needs.
1414

15-
**A static native executable** is a statically linked binary that can be used without any additional library dependencies.
15+
**A static native executable** is a statically linked binary that you can use without any additional library dependencies.
1616
A static native executable is easy to distribute and deploy on a slim or distroless container (a scratch container).
1717
You can create a static native executable by statically linking it against [musl-libc](https://musl.libc.org/), a lightweight, fast and simple `libc` implementation.
1818

19-
**A mostly-static native executable** is a binary that links everything (`zlib`, JDK-shared static libraries) except the standard C library, `libc`. This is an alternative option to statically linking everything. Also, depending on the user's code, it may link `libstdc+` and `libgcc`.
19+
**A mostly-static native executable** is a binary that links all the shared libraries on which the native executable relies (`zlib`, JDK-shared static libraries) except the standard C library, `libc`. This is an alternative option to statically linking everything. Also, depending on the user's code, it may link `libstdc+` and `libgcc`.
2020
This approach is useful for deployment on a distroless container image.
2121

22-
> Note: This currently only works when linked against `libc`.
23-
24-
This guide shows how you can take advantage of Native Image linking options including fully dynamic, fully static, and mostly static (except `libc`) to generate an executable ideal for your deployment scenario.
22+
This guide shows how you can take advantage of Native Image linking options including fully dynamic, fully static, and mostly-static (except `libc`) to generate an executable ideal for your deployment scenario.
2523

2624
## Prerequisites and Preparation
2725

@@ -33,7 +31,7 @@ This guide shows how you can take advantage of Native Image linking options incl
3331
The easiest way to install GraalVM is with [SDKMAN!](https://sdkman.io/jdks#graal).
3432
For other installation options, visit the [Downloads section](https://www.graalvm.org/downloads/).
3533

36-
To be able to create static native applications with Native Image, a `musl` toolchain with the `zlib` library are required on the system.
34+
To create statically linked applications with Native Image, you require a `musl` toolchain with the `zlib` library.
3735
For the best compatibility, use [musl-1.2.4](https://musl.libc.org/releases/musl-1.2.4.tar.gz) or later.
3836
We recommend building `musl` from [source](https://musl.libc.org/) as shown below:
3937

@@ -102,7 +100,13 @@ With the requirements set up, create the demo.
102100
native-image --static --libc=musl EnvMap
103101
```
104102
This produces a native executable with statically linked system libraries.
105-
You can pass other arguments before a class or JAR file. Run it with `./envmap`.
103+
Run it with `./envmap`.
104+
105+
You can confirm the application is fully statically linked using the `ldd` command:
106+
```shell
107+
ldd EnvMap
108+
```
109+
The output should be "not a dynamic executable".
106110

107111
## Build a Mostly-Static Native Executable
108112

@@ -128,8 +132,8 @@ One way to check what dynamic libraries your application depends on is to run `l
128132

129133
#### What is the recommended base container image for deploying a static or mostly-static native executable?
130134

131-
A fully static native executable gives you the most flexibility to choose a base container image—it can run on anything including a `FROM scratch` image.
132-
A mostly-static native executable requires a container image that provides `libc`, but has no additional requirements.
135+
A fully static native executable gives you the most flexibility to choose a base container image—it can even run on a `scratch` image.
136+
A mostly-static native executable requires a container image that provides `libc`, specifically `glibc`, but has no additional requirements.
133137
In both cases, choosing the base container image generally depends on your native executable's specific requirements.
134138

135139
### Related Documentation

0 commit comments

Comments
 (0)