Command-Line Tools

Seven command-line tools providing complete project lifecycle management for SIP binding projects. These tools wrap the core Python API in convenient shell interfaces.

Capabilities

Primary Build Tools

Core tools for building, installing, and distributing SIP projects.

sip-build

Builds project in-situ for development and testing.

sip-build [options]

Usage:

# Build project in current directory
sip-build

# Build with verbose output
sip-build --verbose

# Build with specific configuration
sip-build --build-dir ./build

sip-install

Builds and installs project to Python environment.

sip-install [options]

Usage:

# Install project
sip-install

# Install with custom target directory
sip-install --target-dir /custom/path

# Install with verbose output
sip-install --verbose

sip-wheel

Builds wheel distribution for packaging and distribution.

sip-wheel [options]

Usage:

# Create wheel in current directory
sip-wheel

# Create wheel in specific directory
sip-wheel --wheel-dir ./dist

# Create wheel with verbose output
sip-wheel --verbose

sip-sdist

Builds source distribution for packaging and distribution.

sip-sdist [options]

Usage:

# Create source distribution
sip-sdist

# Create sdist in specific directory
sip-sdist --sdist-dir ./dist

# Create sdist with verbose output
sip-sdist --verbose

Specialized Tools

Tools for specific SIP functionality and compatibility.

sip-module

Generates sip extension module source code and documentation.

sip-module [options]

Key Options:

• --abi-version VERSION - Specify ABI version
• --project DIR - Project directory
• --sdist - Include in source distribution
• --sip-h - Generate sip.h header file
• --sip-rst - Generate RST documentation

Usage:

# Generate sip module for current project
sip-module --project .

# Generate with specific ABI version
sip-module --abi-version 12.8 --project .

# Generate header and documentation
sip-module --sip-h --sip-rst --project .

sip-distinfo

Creates and populates .dist-info directories for package metadata.

sip-distinfo [options]

Key Options:

• --console-script NAME=MODULE:FUNC - Add console script entry
• --gui-script NAME=MODULE:FUNC - Add GUI script entry
• --inventory DIR - Create installation inventory
• --metadata - Create metadata files

Usage:

# Create basic distinfo
sip-distinfo

# Add console script
sip-distinfo --console-script mytool=mymodule:main

# Create full metadata
sip-distinfo --metadata --inventory ./build

Legacy Support

sip5

Legacy SIP v5 compatibility interface for direct code generation.

sip5 [options] specification_file

Key Options:

• -a FILE - Generate QScintilla API file
• -b FILE - Generate build file for directory
• -c DIR - Specify code directory (default: current directory)
• -d FILE - Generate documentation file
• -D - Enable debug mode in generated code
• -e - Enable exception support in generated code
• -f FILE - Generate makefile for directory
• -g - Always release Python GIL
• -I DIR - Add directory to include path for .sip files
• -j COUNT - Split generated code into multiple files
• -k - Generate makefile for building static library
• -l - Enable lazy attribute initialization
• -m FILE - Generate XML module definition file
• -o - Enable docstring generation
• -p MODULE - Set consolidating module name
• -P - Turn on profiling of generated code
• -r - Enable tracing of reference counts
• -s SUFFIX - Set source file suffix (default: .cpp)
• -t TAG - Set SIP version tag
• -T - Disable timestamp in generated code
• -w - Enable warning messages
• -x FEATURE - Disable specified feature
• -X ID:FILE - Generate extracts file
• -y FILE - Generate Python signature (.pys) file
• -z FILE - Generate PyQt .pyi type stub file

Usage:

# Basic code generation
sip5 -c ./generated mymodule.sip

# Generate with API file and type hints
sip5 -c ./generated -a mymodule.api -z mymodule.pyi mymodule.sip

# Advanced generation
sip5 -c ./generated -j 4 -e -o -I /usr/include mymodule.sip

Common Workflows

Development Workflow

# 1. Build project for development
sip-build

# 2. Test changes
python -c "import mymodule; mymodule.test()"

# 3. Install locally
sip-install

Distribution Workflow

# 1. Create source distribution
sip-sdist --sdist-dir ./dist

# 2. Create wheel
sip-wheel --wheel-dir ./dist

# 3. Upload to PyPI (using twine)
twine upload dist/*

Legacy Migration Workflow

# 1. Generate with legacy tool
sip5 -c ./generated mymodule.sip

# 2. Migrate to modern build system
sip-build

# 3. Create wheel
sip-wheel

Error Handling

All SIP command-line tools use standardized error handling:

• Exit Code 0: Success
• Exit Code 1: User error (configuration, missing files, etc.)
• Exit Code 2: System error (compilation failure, permissions, etc.)

Error messages are formatted for user-friendly display and include context about the failure and potential solutions.

Configuration Integration

All tools respect configuration from:

1. pyproject.toml - Primary configuration file
2. Command-line options - Override file settings
3. Environment variables - System-specific overrides

Tools automatically detect and use project configuration, making them suitable for automated build systems and CI/CD pipelines.