0
# Command-Line Tools
1

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

4
## Capabilities
5

6
### Primary Build Tools
7

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

10
#### sip-build
11

12
Builds project in-situ for development and testing.
13

14
```bash { .api }
15
sip-build [options]
16
```
17

18
**Usage:**
19
```bash
20
# Build project in current directory
21
sip-build
22

23
# Build with verbose output
24
sip-build --verbose
25

26
# Build with specific configuration
27
sip-build --build-dir ./build
28
```
29

30
#### sip-install
31

32
Builds and installs project to Python environment.
33

34
```bash { .api }
35
sip-install [options]
36
```
37

38
**Usage:**
39
```bash
40
# Install project
41
sip-install
42

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

46
# Install with verbose output
47
sip-install --verbose
48
```
49

50
#### sip-wheel
51

52
Builds wheel distribution for packaging and distribution.
53

54
```bash { .api }
55
sip-wheel [options]
56
```
57

58
**Usage:**
59
```bash
60
# Create wheel in current directory
61
sip-wheel
62

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

66
# Create wheel with verbose output
67
sip-wheel --verbose
68
```
69

70
#### sip-sdist
71

72
Builds source distribution for packaging and distribution.
73

74
```bash { .api }
75
sip-sdist [options]
76
```
77

78
**Usage:**
79
```bash
80
# Create source distribution
81
sip-sdist
82

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

86
# Create sdist with verbose output
87
sip-sdist --verbose
88
```
89

90
### Specialized Tools
91

92
Tools for specific SIP functionality and compatibility.
93

94
#### sip-module
95

96
Generates sip extension module source code and documentation.
97

98
```bash { .api }
99
sip-module [options]
100
```
101

102
**Key Options:**
103
- `--abi-version VERSION` - Specify ABI version
104
- `--project DIR` - Project directory
105
- `--sdist` - Include in source distribution
106
- `--sip-h` - Generate sip.h header file
107
- `--sip-rst` - Generate RST documentation
108

109
**Usage:**
110
```bash
111
# Generate sip module for current project
112
sip-module --project .
113

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

117
# Generate header and documentation
118
sip-module --sip-h --sip-rst --project .
119
```
120

121
#### sip-distinfo
122

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

125
```bash { .api }
126
sip-distinfo [options]
127
```
128

129
**Key Options:**
130
- `--console-script NAME=MODULE:FUNC` - Add console script entry
131
- `--gui-script NAME=MODULE:FUNC` - Add GUI script entry
132
- `--inventory DIR` - Create installation inventory
133
- `--metadata` - Create metadata files
134

135
**Usage:**
136
```bash
137
# Create basic distinfo
138
sip-distinfo
139

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

143
# Create full metadata
144
sip-distinfo --metadata --inventory ./build
145
```
146

147
### Legacy Support
148

149
#### sip5
150

151
Legacy SIP v5 compatibility interface for direct code generation.
152

153
```bash { .api }
154
sip5 [options] specification_file
155
```
156

157
**Key Options:**
158
- `-a FILE` - Generate QScintilla API file
159
- `-b FILE` - Generate build file for directory
160
- `-c DIR` - Specify code directory (default: current directory)
161
- `-d FILE` - Generate documentation file
162
- `-D` - Enable debug mode in generated code
163
- `-e` - Enable exception support in generated code
164
- `-f FILE` - Generate makefile for directory
165
- `-g` - Always release Python GIL
166
- `-I DIR` - Add directory to include path for .sip files
167
- `-j COUNT` - Split generated code into multiple files
168
- `-k` - Generate makefile for building static library
169
- `-l` - Enable lazy attribute initialization
170
- `-m FILE` - Generate XML module definition file
171
- `-o` - Enable docstring generation
172
- `-p MODULE` - Set consolidating module name
173
- `-P` - Turn on profiling of generated code
174
- `-r` - Enable tracing of reference counts
175
- `-s SUFFIX` - Set source file suffix (default: .cpp)
176
- `-t TAG` - Set SIP version tag
177
- `-T` - Disable timestamp in generated code
178
- `-w` - Enable warning messages
179
- `-x FEATURE` - Disable specified feature
180
- `-X ID:FILE` - Generate extracts file
181
- `-y FILE` - Generate Python signature (.pys) file
182
- `-z FILE` - Generate PyQt .pyi type stub file
183

184
**Usage:**
185
```bash
186
# Basic code generation
187
sip5 -c ./generated mymodule.sip
188

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

192
# Advanced generation
193
sip5 -c ./generated -j 4 -e -o -I /usr/include mymodule.sip
194
```
195

196
## Common Workflows
197

198
### Development Workflow
199

200
```bash
201
# 1. Build project for development
202
sip-build
203

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

207
# 3. Install locally
208
sip-install
209
```
210

211
### Distribution Workflow
212

213
```bash
214
# 1. Create source distribution
215
sip-sdist --sdist-dir ./dist
216

217
# 2. Create wheel
218
sip-wheel --wheel-dir ./dist
219

220
# 3. Upload to PyPI (using twine)
221
twine upload dist/*
222
```
223

224
### Legacy Migration Workflow
225

226
```bash
227
# 1. Generate with legacy tool
228
sip5 -c ./generated mymodule.sip
229

230
# 2. Migrate to modern build system
231
sip-build
232

233
# 3. Create wheel
234
sip-wheel
235
```
236

237
## Error Handling
238

239
All SIP command-line tools use standardized error handling:
240

241
- **Exit Code 0**: Success
242
- **Exit Code 1**: User error (configuration, missing files, etc.)
243
- **Exit Code 2**: System error (compilation failure, permissions, etc.)
244

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

247
## Configuration Integration
248

249
All tools respect configuration from:
250

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

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