mirror of
https://github.com/jart/cosmopolitan.git
synced 2025-07-24 03:20:30 +00:00
Introduce cosmocc flags -mdbg -mtiny -moptlinux
The cosmocc.zip toolchain will now include four builds of the libcosmo.a runtime libraries. You can pass the -mdbg flag if you want to debug your cosmopolitan runtime. You can pass the -moptlinux flag if you don't want windows code lurking in your binary. See tool/cosmocc/README.md for more details on how these flags may be used and their important implications.
This commit is contained in:
Justine Tunney
parent
59692b0882
commit
642e9cb91a
22 changed files with 404 additions and 56 deletions
|
|
@ -142,6 +142,116 @@ and AARCH64, which is K8 and ARMv8.0. You can pass architecture specific
|
|||
flags to use newer ISAs by using the `-Xx86_64` and `-Xaarch64` prefixes
|
||||
like `-Xx86_64-mssse3` and `-Xaarch64-march=armv8.2-a+dotprod`.
|
||||
|
||||
## Flags
|
||||
|
||||
The following supplemental flags are defined by cosmocc:
|
||||
|
||||
- `-mcosmo` causes `_COSMO_SOURCE` to be defined. This has a similar
|
||||
effect to defining `_GNU_SOURCE`. When you use this flag, many
|
||||
non-standard GNU, BSD, and Cosmo Libc APIs will become visible in
|
||||
headers, e.g. `stdlib.h` will now define `ShowCrashReports()`.
|
||||
Including `cosmo.h` has a similar effect, however it's recommended
|
||||
that any program that uses cosmo-specific APIs pass this flag.
|
||||
|
||||
- `-mdbg` may be passed when linking programs. It has the same effect as
|
||||
`export MODE=dbg` in that it will cause an alternative build of the
|
||||
Cosmopolitan Libc runtime to be linked that was built with `-O0 -g`.
|
||||
Under the normal build mode, `--ftrace` output is oftentimes missing
|
||||
important pieces of the puzzle due to inlining. This mode makes it
|
||||
more comprehensible. It's also the only way to make using GDB to
|
||||
troubleshoot issues inside Cosmo Libc work reliably. Please be warned
|
||||
that this flag may enable some heavyweight runtime checks. For
|
||||
example, mmap() will become O(n) rather than O(logn) in an effort to
|
||||
spot data structure corruption. Lastly, the linked Cosmo runtime was
|
||||
compiled with `-fsanitize=undefined` (UBSAN) although you still need
|
||||
to pass that flag too if you want it for your own code.
|
||||
|
||||
- `-mtiny` may be passed when linking programs. It has the same effect
|
||||
as `export MODE=tiny` in that it will cause an alternative build of
|
||||
the Cosmopolitan Libc runtime to be linked that's optimized for code
|
||||
size. In the normal build mode, the smallest possible binary size will
|
||||
be on the order of hundreds of kb, due to heavyweight features like
|
||||
`--ftrace` and `--strace` being part of the mandatory runtime. Those
|
||||
features don't exist in the tiny runtime, which should produce ~147kb
|
||||
fat binaries and ~36kb x86-only binaries. You may also use this flag
|
||||
when compiling objects. Since there's no function tracing, using this
|
||||
will eliminate the NOPs that get inserted into the prologues of your
|
||||
functions to make them hookable, which also greatly reduces code size.
|
||||
Please note that this does not specify an `-O` flag, so you may want
|
||||
to pass `-Os` too. Please note that this mode is granted leeway to
|
||||
trade away performance whenever possible. Functions like memmove()
|
||||
will stop using fancy vectorization which can dramatically decrease
|
||||
the performance of certain use cases. malloc() will stop using cookies
|
||||
which add bloat but are considered important by some people for both
|
||||
security and reporting errors on corruption. APIs will also begin
|
||||
refraining from detecting usage errors that are the fault of the
|
||||
caller, so this mode isn't recommended for development.
|
||||
|
||||
- `-moptlinux` uses the optimized Linux-only version of Cosmopolitan
|
||||
Libc runtime libraries. Your program will only be able to run on
|
||||
Linux. The runtime is compiled at `-O3` although it still supports AMD
|
||||
K8+ (c. 2003). Optimizations like red zone that wouldn't otherwise be
|
||||
possible are enabled. Function call tracing and system call logging is
|
||||
disabled. All the Windows polyfills go away and your binaries will be
|
||||
significantly tinier. The `cosmocc` compiler will generate a shell
|
||||
script with the magic `jartsr='` so you won't get unwanted attention
|
||||
from Windows virus scanners. You're even allowed to use flags like
|
||||
`-fomit-frame-pointer` when you use this mode. Users report optlinux
|
||||
has helped them make the Python interpreter 5% faster, like distros,
|
||||
optlinux will salt the earth if it gains a 1% advantage on benchmark
|
||||
games. Therefore this mode gives you an apples-to-apples comparison
|
||||
between cosmocc versus the gcc/clang configs used by linux distros.
|
||||
|
||||
## Raw Toolchains
|
||||
|
||||
The `cosmocc` and `cosmoar` programs use shell script magic to run both
|
||||
toolchains under the hood. Sometimes this magic doesn't work when you're
|
||||
building software that needs to do things like run the C preprocessor in
|
||||
aarch64 mode. In such cases, cosmocc provides x86\_64 and aarch64 only
|
||||
toolchains which give you more power and control over your builds.
|
||||
|
||||
- `x86_64-unknown-cosmo-cc`, `x86_64-unknown-cosmo-c++`, and
|
||||
`x86_64-linux-cosmo-as` let you build multi-OS programs that only run
|
||||
on x86\_64. You'll need this if you want to compile complex projects
|
||||
like Emacs and OpenSSL. These are shell scripts that help you make
|
||||
sure your software is compiled with the correct set of flags.
|
||||
|
||||
- `aarch64-unknown-cosmo-cc`, `aarch64-unknown-cosmo-c++`, and
|
||||
`aarch64-linux-cosmo-as` let you build multi-OS programs that only run
|
||||
on ARM64. You'll need this if you want to compile complex projects
|
||||
like Emacs and OpenSSL. These are shell scripts that help you make
|
||||
sure your software is compiled with the correct set of flags.
|
||||
|
||||
- `aarch64-linux-cosmo-cc`, `aarch64-linux-cosmo-c++`,
|
||||
`aarch64-linux-cosmo-as`, and `aarch64-linux-cosmo-ld` are the actual
|
||||
compiler executables. Using these grants full control over your
|
||||
compiler and maximum performance. This is the approach favored for
|
||||
instance by the Cosmopolitan Mono Repo's Makefile. If you use these,
|
||||
then you should have zero expectation of support, because you'll be
|
||||
assuming all responsibility for knowing about all the ABI-related
|
||||
flags your Cosmopolitan runtime requires.
|
||||
|
||||
When you use the "unknown" OS compilers, they'll link ELF executables
|
||||
which embed an APE program image. This is so it's possible to have DWARF
|
||||
debugging data. If you say:
|
||||
|
||||
```
|
||||
x86_64-unknown-cosmo-cc -Os -mtiny -o hello hello.c
|
||||
./hello
|
||||
x86_64-linux-cosmo-objcopy -SO binary hello hello.com
|
||||
./hello.com
|
||||
```
|
||||
|
||||
Then you can unwap the raw stripped APE executable and get a much
|
||||
smaller file than you otherwise would using the `-s` flag.
|
||||
|
||||
If you compile your software twice, using both the x86\_64 and aarch64
|
||||
compilers, then it's possible to link the two binaries into a single fat
|
||||
binary yourself via the `apelink` program. To understand how this
|
||||
process works, it works best if you use the `BUILDLOG` variable, to see
|
||||
how the shell script wrappers are doing it. You can also consult the
|
||||
build configs of the ahgamut/superconfigure project on GitHub.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
Your `cosmocc` compiler runs a number commands under the hood. If
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue