translate Command

Translate Python modules to C++ with traditional Makefile generation

The translate command converts Python source code to C++ and generates a Makefile for compilation. This is the traditional Shed Skin workflow.

Syntax

shedskin translate [options] <module.py>

The translate command is the default. Running shedskin myprogram.py is equivalent to shedskin translate myprogram.py.

Overview

The translate command performs:

1. Parsing - Reads and validates your Python source code
2. Type Inference - Analyzes types using iterative flow analysis
3. Code Generation - Generates optimized C++ source files
4. Makefile Generation - Creates a Makefile for compilation (optional)

Basic Examples

Translate to C++

shedskin translate example.py

Output:

*** SHED SKIN Python-to-C++ Compiler 0.9.12 ***
Copyright 2005-2026 Mark Dufour and contributors; License GNU GPL version 3

>> reading Python
>> type inference
>> code generation

[prebuild time: 0.38 seconds]

Generates:

• example.cpp - C++ implementation
• example.hpp - C++ header file
• Makefile - Build configuration

Translate and compile immediately

shedskin translate --compile example.py

This translates to C++, then runs make to build the executable.

Translate, compile, and run

shedskin translate --run example.py

Complete workflow in one command: translate → compile → execute.

Generate extension module

shedskin translate --extmod mymodule.py
make

Creates a Python extension module that can be imported.

Generated C++ Structure

Executable Program

For program.py, Shed Skin generates:

program.py              # Your Python source
program.cpp             # Generated C++ implementation
program.hpp             # Generated C++ header
Makefile                # Build configuration

The C++ code includes:

• Type-specialized functions
• Optimized data structures
• Integration with Shed Skin runtime library

Extension Module

For extension modules (--extmod):

mymodule.py             # Your Python source  
mymodule.cpp            # C++ implementation with Python bindings
mymodule.hpp            # C++ header
Makefile                # Builds shared library (.so/.dylib/.pyd)

Command Options

Basic Options

name · string · required

Python file or module to translate (e.g., program.py)

-c, --compile · boolean

Directly compile the translated code using the generated Makefile

-r, --run · boolean

Translate, compile, and run the executable in one step

-o, --outputdir · string

Specify output directory for generated C++ files (default: current directory)

-e, --extmod · boolean

Generate a Python extension module instead of a standalone executable

-x, --executable · boolean

Explicitly generate a standalone executable (this is the default)

-s, --silent · boolean

Silent mode - only show warnings, suppress informational messages

-d, --debug · integer

Set debug logging level:

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

Makefile Options

--nomakefile · boolean

Disable Makefile generation (only generate C++ files)

-m, --makefile · string

Specify alternate Makefile name (default: Makefile)

-F, --flags · string

Provide path to alternate Makefile flags configuration file

-S, --static-libs · boolean

Use static linking if possible (creates standalone binaries)

-D, --dry-run · boolean

Only print the compilation command without executing it

--nocleanup · boolean

Disable cleanup of generated intermediate files

Type Configuration

--int32 · boolean

Use 32-bit integers throughout the generated code

--int64 · boolean

Use 64-bit integers for better range at slight performance cost

--int128 · boolean

Use 128-bit integers (Linux/macOS only, not supported on Windows)

--float32 · boolean

Use 32-bit floating point (single precision) for better performance

--float64 · boolean

Use 64-bit floating point (double precision) for better accuracy

Performance & Safety Options

-b, --nobounds · boolean

Disable bounds checking on array/list access. Significant performance boost but removes safety checks.

-w, --nowrap · boolean

Disable wrap-around checking for negative indices (e.g., list[-1])

--noassert · boolean

Disable Python assert statements in generated code

--nogc · boolean

Disable garbage collection. Use only if you’re certain about memory management.

-t, --traceback · boolean

Print full traceback for uncaught exceptions in compiled code

Linking Options

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

Add include directories for C++ compilation. Can be specified multiple times.

Example: -I /usr/local/include -I ./headers

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

Add library directories for linking. Can be specified multiple times.

Example: -L /usr/local/lib -L ./lib

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

Add libraries to link against. Can be specified multiple times.

Example: -l pthread -l m

-X, --extra-lib · string

Add an extra directory for Shed Skin builtins library extensions

Other Options

--local-deps · boolean

Use dependencies from bundled ext/ sources instead of system libraries

--collect-stats · boolean

Collect and report detailed compilation statistics

Advanced Examples

Generate C++ only (no Makefile)

shedskin translate --nomakefile myprogram.py

Useful when integrating with custom build systems.

Custom Makefile name

shedskin translate --makefile Makefile.custom myprogram.py

Performance-optimized translation

shedskin translate --nobounds --nowrap --noassert --float32 myprogram.py
make

Maximum performance by disabling safety checks and using 32-bit floats.

Translation with custom output directory

shedskin translate --outputdir ./generated myprogram.py
cd generated
make

Extension module with type configuration

shedskin translate --extmod --int64 --float64 mymodule.py
make

Debug build with tracebacks

shedskin translate --debug 3 --traceback myprogram.py
make

Static linking for portable binaries

shedskin translate --static-libs myprogram.py
make

Dry run to see compilation command

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

Shows what make would execute without actually compiling.

Translate vs Build

Use translate when:

• You want a simple Makefile workflow
• You need direct control over the compilation process
• You’re integrating with existing Make-based projects
• You want to customize the generated Makefile

Use build when:

• You want modern CMake-based workflow
• You need better dependency management
• You want IDE integration (most IDEs support CMake)
• You need multi-configuration builds (Debug/Release)

See build command for details on the CMake workflow.

Compiling the Generated Code

Using the generated Makefile

shedskin translate myprogram.py
make
./myprogram

Using the shorthand

shedskin translate --compile myprogram.py
./myprogram

Complete workflow

shedskin translate --run myprogram.py

Output Files

C++ Source Files

program.cpp - Main implementation:

// Type-specialized function implementations
// Optimized data structure operations
// Integration with Shed Skin runtime

program.hpp - Header declarations:

// Class and function declarations
// Template specializations
// Namespace definitions

Makefile

The generated Makefile includes:

• Compiler flags for optimization
• Include paths for Shed Skin runtime
• Linking configuration
• Platform-specific settings

You can customize the Makefile after generation or use --flags to provide alternate flags.

Extension Module Usage

After compiling an extension module:

shedskin translate --extmod --compile mymodule.py

Use it from Python:

import mymodule

# Call functions from the compiled module
result = mymodule.fast_function(data)

The compiled C++ code provides the same API as your Python module but runs at native speed.

When to Use Translate

The translate command is ideal for:

• Learning how Shed Skin generates C++ code
• Inspecting the generated code for optimization opportunities
• Integrating with existing Make-based build systems
• Quick prototyping and experimentation
• Manual customization of build process

For production builds and larger projects, consider using the build command with CMake.

See Also

• build command - Modern CMake-based compilation
• Command-line options - Complete option reference
• CLI overview - All available commands