Calling C printf from Nim using FFI: Step‑by‑step guide

Desired outcome

Compile a Nim program that invokes the C printf function and runs without linker errors, producing the expected printed output.

Prerequisites

• Nim compiler version 1.6 or newer (nim --version).
• A C compiler compatible with Nim’s backend (e.g., gcc or clang).
• The nimble package manager (usually bundled with Nim).
• A terminal with normal user privileges; no administrator rights are required for compilation.

Procedure

1. Create the Nim source file. Save the following as hello.nim:

   {#.pragma: cimport, <stdio.h>, "cdecl".#}
   proc printf*(cstring: cstring) {.importc, "printf", header: <stdio.h>.}
   
   when isMainModule:
     printf("Hello from C via Nim!\n")
   

   The {.pragma: cimport, <stdio.h>, "cdecl".} pragma tells Nim to generate an #include <stdio.h> in the intermediate C file and to use the cdecl calling convention, which matches the default for printf on most platforms.

2. Compile the program. Run the following command in the directory containing hello.nim:

   nim c --passC:-lc hello.nim

   The --passC:-lc flag forwards -lc to the C linker, ensuring the standard C library (which provides printf) is linked. On Windows the flag can be omitted because the C runtime is linked by default, but including it does not cause harm.

3. Execute the resulting binary.

   ./hello   # on Linux/macOS
   hello.exe # on Windows (if using the default name)

Expected checks

• The compilation step finishes with no warnings or errors.
• Running the executable prints exactly:

  Hello from C via Nim!

• If you inspect the generated C intermediate file (hello.c), you should see an extern declaration similar to:

  extern int printf(const char *);

Recovery options (troubleshooting)

• Linking fails with “undefined reference to `printf’”: verify that -lc is being passed. You can see the full compile command by adding --verbosity:2. If the flag is missing, add it explicitly as shown.
• Calling convention mismatch: ensure the pragma includes "cdecl". On some platforms stdcall is used for certain Windows APIs; using the wrong convention leads to stack corruption.
• Inspect generated C code: run nim c --showPass:C hello.nim to dump the intermediate C file without assembling. Check that the printf declaration matches the expected signature.
• Debugging: compile with -d:danger to disable optimizations, then use gdb or lldb to set a breakpoint at printf and confirm control flows from Nim.

Limitations and safety considerations

• Nim’s garbage collector may relocate memory. Never pass a pointer to Nim‑managed data (e.g., a string or sequence) to C unless you pin it with GC_ref or allocate it with alloc0/dealloc from the system module.
• When using macros or compile‑time execution ({.compileTime.}), ensure FFI declarations are outside macro expansion; otherwise the bindings could be stale after macro re‑evaluation.
• Data type mismatches (e.g., passing a int where C expects long) cause undefined behavior. Match the C types exactly using Nim’s cint, clong, cstring, etc.

Practical verification

1. Run the executable and capture its output:

./hello > output.txt
cat output.txt

2. Compare the content of output.txt with the expected line Hello from C via Nim!. Any deviation indicates a problem in the FFI setup.
3. Optionally, diff the generated C file against a known good template to ensure the #include and extern lines are present.

Rollback

Compiling creates the executable (hello or hello.exe) and intermediate files (hello.c, hello.o). To return to a clean state, delete them:

rm -f hello hello.exe hello.c hello.o
# on Windows: del hello.exe hello.c hello.o

This removes all artifacts produced by the procedure without affecting source files or the Nim toolchain.