FAQ

Issues

"I want to learn more about X program, but I can't find any documentation on it"

If the program has its own directory, check for the files README.md (original author's) and README.cosmo (Cosmo-specific changelog). If it's in third_party/, look for its help files online.

If that fails, check the source code for comments and documentation strings. If that's still not good enough, try reading the code -- understandable code is a priority for the developers.

"I'm troubleshooting and need more info about my program's execution"

All Cosmo binaries include two special flags: --strace which echoes system calls, and --ftrace which echoes function calls. This provides visibility into your program on a level that normally requires a debugger.

"My program won't execute in certain situations"

An example: the program runs fine when run straight from the command line, but usage from find -exec fails with the error ENOACCESS.

• Running the program under a shell invocation, such as sh -c 'binary.com args...' may succeed.
• Every Cosmopolitan binary can strip its own headers, to fit your native binary format with binary.com --assimilate. This is non-reversible and means that the program will no longer work on systems with different executable formats (the groups being Windows, Linux/BSD, and Mac). However, it may dodge this issue. Be sure to back up your programs before running.

"Zipping files into an executable breaks the executable"

Cosmo executables are usually also ZIP files, e.g. redbean.com, Lua.com, QuickJS, etc. You should be able to easily view their contents with any ZIP program, e.g. unzip -vl redbean.com. So support for reading files is universal. The issue is with modifying. Cosmo binaries are essentially what used to be called "self-extracting archives". Many modern ZIP tools don't understand this and will destroy the executable content when they rearrange files within the archive. It's particularly true of GUI programs on Windows. The best tool to use for changing your zip files is InfoZIP, which is available on nearly every Mac and UNIX install as the standard zip and unzip commands. Those tools work great and won't corrupt your executable. If you want a GUI, then the one that's known to work is PKZIP for Windows which costs $30. The Cosmopolitan mono-repo also has a third_party/zip/zip.com program that you can use, which is a port of InfoZIP.

Binary output format from cosmocc is extension-dependent

To get an APE out of cosmocc, name the output with a .com extension.

cosmocc hello.c -o hello.com
hd hello.com | head -2
    00000000  4d 5a 71 46 70 44 3d 27  0a 00 00 10 00 f8 00 00  |MZqFpD='........|
    00000010  00 00 00 00 00 01 00 08  40 00 00 00 00 00 00 00  |........@.......|
cosmocc hello.c -o hello
hd hello | head -2
    00000000  7f 45 4c 46 02 01 01 00  00 00 00 00 00 00 00 00  |.ELF............|
    00000010  02 00 3e 00 01 00 00 00  7c 45 40 00 00 00 00 00  |..>.....|E@.....|

Other ways to get APE binaries:

• use fatcosmocc, which always outputs APE
• apecopy foo.elf foo.ape