Command-Line Options

Complete reference for all Shed Skin compiler command-line flags and options

Comprehensive reference for all command-line options available in Shed Skin.

Global Options

These options are available for most commands (build, translate, run).

Output Configuration

-o, --outputdir DIR · string

Specify output directory for generated C++ files.

Default: Current directory

Example:

shedskin build --outputdir ./generated myprogram.py

Generated files (myprogram.cpp, myprogram.hpp) will be placed in ./generated/.

-s, --silent · boolean

Silent mode - suppress informational messages and only show warnings.

Default: false (show all output)

Example:

shedskin build --silent myprogram.py

Useful for scripting and automated builds.

-d, --debug LEVEL · integer

Set debug logging level (1-3).

Levels:

• 1 - Basic debug information
• 2 - Detailed debug output
• 3 - Enables iterative flow analysis (IFA) debug logging

Default: No debug output

Example:

shedskin build --debug 2 myprogram.py

Compilation Mode

-e, --extmod · boolean

Generate a Python extension module instead of a standalone executable.

Default: false (generate executable)

Example:

shedskin build --extmod mymodule.py

Creates a .so (Linux), .dylib (macOS), or .pyd (Windows) file that can be imported from Python:

import mymodule

-x, --executable · boolean

Explicitly generate a standalone executable (this is the default behavior).

Example:

shedskin build --executable myprogram.py

Integer Type Options

Control the integer type used throughout the generated C++ code.

--int32 · boolean

Use 32-bit integers (int32_t).

Range: -2,147,483,648 to 2,147,483,647

Effect: Smaller memory footprint, potential performance improvement on some architectures.

Example:

shedskin build --int32 myprogram.py

--int64 · boolean

Use 64-bit integers (int64_t).

Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807

Effect: Larger range, default on most 64-bit systems.

Example:

shedskin build --int64 myprogram.py

--int128 · boolean

Use 128-bit integers (__int128).

Range: Extremely large integers (±10³⁸)

Platform: Linux and macOS only (not supported on Windows)

Effect: Maximum integer range at performance cost.

Example:

shedskin build --int128 myprogram.py

Not supported on Windows. Will exit with error if attempted.

Floating Point Type Options

Control the floating point precision used in generated code.

--float32 · boolean

Use 32-bit floating point numbers (float, single precision).

Precision: ~7 decimal digits

Effect: Better performance, lower memory usage, reduced precision.

Use case: Graphics, game development, non-critical calculations.

Example:

shedskin build --float32 myprogram.py

--float64 · boolean

Use 64-bit floating point numbers (double, double precision).

Precision: ~15 decimal digits

Effect: Higher accuracy, standard for scientific computing.

Use case: Scientific computing, financial calculations, precise math.

Example:

shedskin build --float64 myprogram.py

Performance & Safety Options

These flags disable safety checks for improved performance.

-b, --nobounds · boolean

Disable bounds checking on array and list access.

Default: Bounds checking enabled

Performance gain: 10-30% in array-heavy code

Risk: Buffer overflows, undefined behavior on out-of-bounds access

Example:

shedskin build --nobounds myprogram.py

# With bounds checking: raises IndexError
# With --nobounds: undefined behavior
arr = [1, 2, 3]
x = arr[10]  # Out of bounds

Only use when you’re certain all array accesses are within bounds.

-w, --nowrap · boolean

Disable wrap-around checking for negative indices.

Default: Wrap-around checking enabled

Performance gain: 5-15% in code using negative indexing

Risk: Incorrect behavior with negative indices

Example:

shedskin build --nowrap myprogram.py

# With wrap-around: arr[-1] returns last element
# With --nowrap: undefined behavior
arr = [1, 2, 3]
x = arr[-1]

Don’t use if your code relies on negative indexing (e.g., list[-1]).

--noassert · boolean

Disable assert statements in generated code.

Default: Assertions enabled

Performance gain: Minimal, mostly code size reduction

Risk: Loss of runtime validation

Example:

shedskin build --noassert myprogram.py

# This assertion won't be checked with --noassert
assert x > 0, "x must be positive"

Useful for production builds where assertions are expensive.

--nogc · boolean

Disable garbage collection.

Default: Garbage collection enabled (Boehm GC)

Effect: All allocations are permanent (memory leak risk)

Use case: Short-lived programs, embedded systems with manual memory management

Example:

shedskin build --nogc myprogram.py

Use only for programs with predictable memory usage that run briefly.

-t, --traceback · boolean

Print full traceback for uncaught exceptions.

Default: Basic error messages only

Effect: Shows stack trace when exceptions occur in compiled code

Example:

shedskin build --traceback myprogram.py

Useful for debugging runtime errors in compiled programs.

Linking & Include Options

-I, --include-dirs DIR · string[]

Add include directories for C++ compilation.

Can be specified multiple times

Example:

shedskin build \
  -I /usr/local/include \
  -I ./external/headers \
  myprogram.py

Adds -I<DIR> to compiler flags.

-L, --link-dirs DIR · string[]

Add library directories for linking.

Can be specified multiple times

Example:

shedskin build \
  -L /usr/local/lib \
  -L ./external/lib \
  myprogram.py

Adds -L<DIR> to linker flags.

-l, --link-libs LIB · string[]

Add libraries to link against.

Can be specified multiple times

Example:

shedskin build \
  -l pthread \
  -l m \
  -l sqlite3 \
  myprogram.py

Adds -l<LIB> to linker flags.

-X, --extra-lib DIR · string

Add an extra directory for Shed Skin builtins library extensions.

Example:

shedskin build --extra-lib ./custom-libs myprogram.py

Useful for custom implementations of Shed Skin built-in libraries.

CMake Options

These options are specific to the build and run commands.

--generator G · string

Specify CMake build system generator.

Common values:

• "Unix Makefiles" (default on Linux/macOS)
• "Ninja" (faster builds)
• "Visual Studio 17 2022" (Windows)
• "Xcode" (macOS)

Example:

shedskin build --generator Ninja myprogram.py

--jobs N · integer

Build in parallel using N jobs.

Default: Single-threaded build

Example:

# Use 8 parallel jobs
shedskin build --jobs 8 myprogram.py

# Use all available CPU cores
shedskin build --jobs $(nproc) myprogram.py

Significantly speeds up compilation of large projects.

--build-type T · string · default: "Debug"

Set CMake build type.

Values:

• Debug - No optimization, debug symbols, assertions enabled
• Release - Full optimization (-O3), no debug symbols
• RelWithDebInfo - Optimization with debug symbols
• MinSizeRel - Optimize for size (-Os)

Example:

shedskin build --build-type Release myprogram.py

On Windows, defaults to Release due to debug symbol availability issues.

--reset · boolean

Reset CMake build directory before building.

Effect: Removes build/ directory and regenerates from scratch

Example:

shedskin build --reset myprogram.py

Useful when CMake cache is corrupted or configuration changed significantly.

--test · boolean

Run ctest after building.

Example:

shedskin build --test myprogram.py

Automatically runs test suite after successful build.

--ccache · boolean

Enable ccache for faster rebuilds.

Requires: ccache installed on system

Effect: Caches compilation results for faster subsequent builds

Example:

shedskin build --ccache myprogram.py

Can reduce rebuild time by 5-10x for unchanged files.

--target TARGET · string[]

Build only specified CMake targets.

Can specify multiple targets

Example:

shedskin build --target myprogram --target tests myprogram.py

--nowarnings · boolean

Disable -Wall compilation warnings.

Default: Warnings enabled

Example:

shedskin build --nowarnings myprogram.py

Useful when working with generated code that produces harmless warnings.

Dependency Management Options

Control how Shed Skin manages external dependencies.

--local-deps · boolean · default: "true"

Build dependencies from bundled ext/ sources.

Default: Automatically enabled if no other option specified

Example:

shedskin build --local-deps myprogram.py

Uses dependencies bundled with Shed Skin installation.

--spm · boolean

Install CMake dependencies using SPM package manager.

Example:

shedskin build --spm myprogram.py

Requires SPM to be installed and configured.

--fetchcontent · boolean

Install CMake dependencies using FetchContent.

Effect: Downloads dependencies at configure time

Example:

shedskin build --fetchcontent myprogram.py

Useful for reproducible builds without pre-installed dependencies.

Translate-Specific Options

These options only apply to the translate command.

-c, --compile · boolean

Directly compile translated code using generated Makefile.

Example:

shedskin translate --compile myprogram.py

Equivalent to:

shedskin translate myprogram.py
make

-r, --run · boolean

Translate, compile, and run the executable.

Example:

shedskin translate --run myprogram.py

Complete workflow in one command.

--nomakefile · boolean

Disable Makefile generation (only generate C++ files).

Example:

shedskin translate --nomakefile myprogram.py

Useful when integrating with custom build systems.

-m, --makefile NAME · string

Specify alternate Makefile name.

Default: Makefile

Example:

shedskin translate --makefile Makefile.custom myprogram.py

-F, --flags FILE · string

Provide path to alternate Makefile flags file.

Example:

shedskin translate --flags ./build-flags.txt myprogram.py

The flags file must exist or an error is raised.

-S, --static-libs · boolean

Use static linking if possible.

Effect: Creates standalone binaries with no external dependencies

Example:

shedskin translate --static-libs myprogram.py

Useful for creating portable executables.

-D, --dry-run · boolean

Only print compilation command without executing.

Example:

shedskin translate --compile --dry-run myprogram.py

Shows what would be executed without actually compiling.

--nocleanup · boolean

Disable cleanup of generated intermediate files.

Example:

shedskin translate --nocleanup myprogram.py

Keeps all temporary files for inspection.

Statistics & Debugging

--collect-stats · boolean

Collect and report detailed compilation statistics.

Example:

shedskin build --collect-stats myprogram.py

Shows:

• Prebuild time (parsing and analysis)
• Build time (C++ compilation)
• Run time (if applicable)
• Module statistics

Option Combinations

Maximum Performance

shedskin build \
  --build-type Release \
  --nobounds \
  --nowrap \
  --noassert \
  --float32 \
  --ccache \
  --jobs $(nproc) \
  myprogram.py

Maximum Safety (Debug)

shedskin build \
  --build-type Debug \
  --debug 3 \
  --traceback \
  --float64 \
  --int64 \
  myprogram.py

Extension Module for Production

shedskin build \
  --extmod \
  --build-type Release \
  --nobounds \
  --nowrap \
  --jobs $(nproc) \
  mymodule.py

Portable Static Binary

shedskin translate \
  --static-libs \
  --compile \
  --nobounds \
  --float32 \
  myprogram.py

See Also

• CLI Overview - Command reference
• build command - CMake workflow
• translate command - Makefile workflow