> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shedskin/shedskin/llms.txt
> Use this file to discover all available pages before exploring further.

# build Command

> Build Python modules to native executables or extension modules using CMake

The `build` command is the modern, recommended way to compile Python programs with Shed Skin. It uses CMake for build configuration and dependency management.

## Syntax

```bash theme={null}
shedskin build [options] <module.py>
```

## Overview

The build command performs these steps:

1. **Parse** - Reads and validates your Python source code
2. **Analyze** - Performs type inference and static analysis
3. **Generate** - Creates C++ source files and CMakeLists.txt
4. **Build** - Compiles C++ code to native executable or extension module

## Basic Examples

### Build a standalone executable

```bash theme={null}
shedskin build 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
>> building with cmake

[prebuild time: 0.45 seconds]
```

The executable is created at `build/example`.

### Build an extension module

```bash theme={null}
shedskin build --extmod mymodule.py
```

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

```python theme={null}
import mymodule  # Uses the compiled C++ extension
```

### Build with optimization flags

```bash theme={null}
shedskin build --nobounds --nowrap --build-type Release example.py
```

This disables safety checks and uses optimized compilation for maximum performance.

## Output Directory Structure

After running `build`, your project will have:

```
project/
├── example.py           # Original Python source
├── example.cpp          # Generated C++ implementation  
├── example.hpp          # Generated C++ header
├── CMakeLists.txt       # Generated CMake configuration
└── build/               # CMake build directory
    ├── example          # Compiled executable
    ├── CMakeCache.txt
    ├── CMakeFiles/
    └── Makefile         # Generated by CMake
```

## Command Options

### Basic Options

<ParamField path="name" type="string" required>
  Python file or module to compile (e.g., `program.py`)
</ParamField>

<ParamField path="-o, --outputdir" type="string">
  Specify output directory for generated C++ files (default: current directory)
</ParamField>

<ParamField path="-e, --extmod" type="boolean">
  Generate a Python extension module instead of a standalone executable
</ParamField>

<ParamField path="-x, --executable" type="boolean">
  Explicitly generate a standalone executable (this is the default)
</ParamField>

<ParamField path="-s, --silent" type="boolean">
  Silent mode - only show warnings, suppress informational output
</ParamField>

<ParamField path="-d, --debug" type="integer">
  Set debug logging level (1-3). Level 3 enables detailed type inference logging
</ParamField>

### Type Configuration

<ParamField path="--int32" type="boolean">
  Use 32-bit integers (default: platform-dependent)
</ParamField>

<ParamField path="--int64" type="boolean">
  Use 64-bit integers
</ParamField>

<ParamField path="--int128" type="boolean">
  Use 128-bit integers (not supported on Windows)
</ParamField>

<ParamField path="--float32" type="boolean">
  Use 32-bit floating point numbers
</ParamField>

<ParamField path="--float64" type="boolean">
  Use 64-bit floating point numbers (double precision)
</ParamField>

### Performance & Safety Options

<ParamField path="-b, --nobounds" type="boolean">
  Disable array bounds checking for better performance
</ParamField>

<ParamField path="-w, --nowrap" type="boolean">
  Disable wrap-around checking for negative indices
</ParamField>

<ParamField path="--noassert" type="boolean">
  Disable assert statements in generated code
</ParamField>

<ParamField path="--nogc" type="boolean">
  Disable garbage collection (use with caution)
</ParamField>

<ParamField path="-t, --traceback" type="boolean">
  Print traceback for uncaught exceptions in compiled code
</ParamField>

### CMake Build Options

<ParamField path="--generator" type="string">
  Specify CMake build system generator (e.g., "Ninja", "Unix Makefiles")
</ParamField>

<ParamField path="--jobs" type="integer">
  Build in parallel using N jobs (e.g., `--jobs 4`)
</ParamField>

<ParamField path="--build-type" type="string" default="Debug">
  Set CMake build type: `Debug`, `Release`, `RelWithDebInfo`, or `MinSizeRel`
</ParamField>

<ParamField path="--reset" type="boolean">
  Reset CMake build directory before building
</ParamField>

<ParamField path="--test" type="boolean">
  Run ctest after building
</ParamField>

<ParamField path="--ccache" type="boolean">
  Enable ccache for faster rebuilds
</ParamField>

<ParamField path="--target" type="string[]">
  Build only specified CMake targets (e.g., `--target myprogram`)
</ParamField>

<ParamField path="--nowarnings" type="boolean">
  Disable `-Wall` compilation warnings
</ParamField>

### Dependency Management

<ParamField path="--local-deps" type="boolean" default="true">
  Build dependencies from bundled ext/ sources (default if no other option specified)
</ParamField>

<ParamField path="--spm" type="boolean">
  Install CMake dependencies using SPM package manager
</ParamField>

<ParamField path="--fetchcontent" type="boolean">
  Install CMake dependencies using FetchContent
</ParamField>

### Advanced Options

<ParamField path="-I, --include-dirs" type="string[]">
  Add include directories for C++ compilation (can be specified multiple times)
</ParamField>

<ParamField path="-L, --link-dirs" type="string[]">
  Add library directories for linking (can be specified multiple times)
</ParamField>

<ParamField path="-l, --link-libs" type="string[]">
  Add libraries to link against (can be specified multiple times)
</ParamField>

<ParamField path="-X, --extra-lib" type="string">
  Add an extra builtins library directory
</ParamField>

<ParamField path="--collect-stats" type="boolean">
  Collect and report compilation statistics
</ParamField>

## Advanced Examples

### Parallel build with release optimization

```bash theme={null}
shedskin build --jobs 8 --build-type Release --nobounds myprogram.py
```

### Build with custom output directory

```bash theme={null}
shedskin build --outputdir ./generated myprogram.py
```

Generated C++ files go to `./generated/`, executable goes to `build/`.

### Build extension with 64-bit integers

```bash theme={null}
shedskin build --extmod --int64 mymodule.py
```

### Debug build with tracebacks

```bash theme={null}
shedskin build --debug 2 --traceback --build-type Debug myprogram.py
```

### Using Ninja generator for faster builds

```bash theme={null}
shedskin build --generator Ninja --jobs 8 myprogram.py
```

### Performance-optimized build

```bash theme={null}
shedskin build \
  --build-type Release \
  --nobounds \
  --nowrap \
  --noassert \
  --ccache \
  --jobs $(nproc) \
  myprogram.py
```

## Build vs Translate

Choose **build** when you want:

* Modern CMake-based workflow
* Better dependency management
* IDE integration (CMake support)
* Multi-configuration builds (Debug/Release)
* Cross-platform portability

Choose **translate** when you want:

* Simple Makefile-based builds
* Direct control over compilation
* Integration with existing Makefile workflows

## Running the Compiled Program

After building, run your executable:

```bash theme={null}
# Standalone executable
./build/myprogram

# Or use the run command to build and run in one step
shedskin run myprogram.py
```

For extension modules:

```python theme={null}
# The .so/.dylib/.pyd file must be in Python's import path
import mymodule
result = mymodule.some_function()
```

## Troubleshooting

### CMake not found

Shed Skin requires CMake 3.15 or later. Install it using:

```bash theme={null}
# Ubuntu/Debian
sudo apt install cmake

# macOS
brew install cmake

# Windows
choco install cmake
```

### Build directory issues

If you encounter CMake cache problems, reset the build:

```bash theme={null}
shedskin build --reset myprogram.py
```

### Slow builds

Speed up compilation:

```bash theme={null}
shedskin build --ccache --jobs $(nproc) myprogram.py
```

## See Also

* [translate command](/cli/translate) - Traditional Makefile-based workflow
* [CLI overview](/cli/overview) - All available commands
* [Command-line options](/cli/options) - Complete reference