0
# Setup and Configuration
1

2
Enhanced setup function and argument parsing utilities that replace setuptools.setup() with integrated CMake build system support. Handles CMake configuration, argument parsing, and build orchestration while maintaining full compatibility with setuptools features.
3

4
## Capabilities
5

6
### Enhanced Setup Function
7

8
The main entry point for scikit-build that replaces setuptools.setup() with CMake integration capabilities. Configures and builds C/C++/Fortran extensions using CMake while preserving all standard setuptools functionality.
9

10
```python { .api }
11
def setup(
12
    *,
13
    cmake_args: Sequence[str] = (),
14
    cmake_install_dir: str = "",
15
    cmake_source_dir: str = "",
16
    cmake_with_sdist: bool = False,
17
    cmake_languages: Sequence[str] = ("C", "CXX"),
18
    cmake_minimum_required_version: str | None = None,
19
    cmake_process_manifest_hook: Callable[[list[str]], list[str]] | None = None,
20
    cmake_install_target: str = "install",
21
    **kw: Any,
22
) -> upstream_Distribution:
23
    """
24
    Enhanced setuptools.setup() with CMake integration.
25
    
26
    Parameters:
27
    - cmake_args: Arguments passed to CMake configuration command
28
    - cmake_install_dir: Installation directory for CMake (relative to build directory)
29
    - cmake_source_dir: Source directory containing CMakeLists.txt (relative to setup.py directory)
30
    - cmake_with_sdist: Include CMake files in source distribution
31
    - cmake_languages: Languages to enable in CMake project (C, CXX, Fortran)
32
    - cmake_minimum_required_version: Minimum CMake version required for the project
33
    - cmake_process_manifest_hook: Function to process list of installed files
34
    - cmake_install_target: CMake target to use for installation (default: "install")
35
    - **kw: All standard setuptools.setup() arguments
36
    
37
    Returns:
38
    setuptools Distribution object
39
    """
40
```
41

42
### Argument Parser Creation
43

44
Creates argument parser for scikit-build specific command-line options that can be used in setup scripts or command-line tools.
45

46
```python { .api }
47
def create_skbuild_argparser() -> argparse.ArgumentParser:
48
    """
49
    Create and return a scikit-build argument parser.
50
    
51
    Includes options for:
52
    - --build-type: CMake build type (Debug/Release)
53
    - -G/--generator: CMake build system generator
54
    - -j: Number of parallel build jobs
55
    - --cmake-executable: Path to cmake executable
56
    - --install-target: CMake installation target
57
    - --skip-generator-test: Skip generator compatibility test
58
    
59
    Returns:
60
    ArgumentParser configured with scikit-build options
61
    """
62
```
63

64
### Argument Parsing Functions
65

66
Parses scikit-build arguments and separates them from other command-line arguments for proper handling by the build system.
67

68
```python { .api }
69
def parse_skbuild_args(
70
    args: Sequence[str], 
71
    cmake_args: Sequence[str], 
72
    build_tool_args: Sequence[str]
73
) -> tuple[list[str], str | None, bool, list[str], list[str]]:
74
    """
75
    Parse arguments in the scikit-build argument set.
76
    
77
    Converts specified arguments to proper format and appends to cmake_args 
78
    and build_tool_args.
79
    
80
    Parameters:
81
    - args: Input arguments to parse
82
    - cmake_args: Existing CMake arguments to extend
83
    - build_tool_args: Existing build tool arguments to extend
84
    
85
    Returns:
86
    Tuple of (remaining_args, cmake_executable, skip_generator_test, 
87
             updated_cmake_args, updated_build_tool_args)
88
    """
89

90
def parse_args() -> tuple[list[str], str | None, bool, list[str], list[str]]:
91
    """
92
    Parse command-line arguments sys.argv and return argument sets.
93
    
94
    Automatically parses sys.argv and separates scikit-build arguments
95
    from other arguments.
96
    
97
    Returns:
98
    Tuple of (remaining_args, cmake_executable, skip_generator_test,
99
             cmake_args, build_tool_args)
100
    """
101
```
102

103
### Package Data Configuration
104

105
Determines default behavior for including package data files based on project configuration.
106

107
```python { .api }
108
def get_default_include_package_data() -> bool:
109
    """
110
    Include package data if pyproject.toml contains project or tool.setuptools table.
111
    
112
    Checks pyproject.toml for modern Python packaging configuration and returns
113
    appropriate default for include_package_data parameter.
114
    
115
    Returns:
116
    True if package data should be included by default, False otherwise
117
    """
118
```
119

120
### Utility Functions
121

122
Helper functions for processing package paths and file organization during the build process.
123

124
```python { .api }
125
def strip_package(package_parts: Sequence[str], module_file: str) -> str:
126
    """
127
    Strip package prefix from module file paths.
128
    
129
    Removes package directory components from file paths to get relative
130
    module paths for installation.
131
    
132
    Parameters:
133
    - package_parts: List of package directory components
134
    - module_file: Full path to module file
135
    
136
    Returns:
137
    Relative module file path with package prefix removed
138
    """
139
```
140

141
## Usage Examples
142

143
### Basic Extension Setup
144

145
```python
146
from skbuild import setup
147

148
setup(
149
    name="my_extension",
150
    version="1.0.0",
151
    description="C++ extension for Python",
152
    cmake_source_dir="src",
153
    cmake_args=[
154
        "-DCMAKE_BUILD_TYPE=Release",
155
        "-DPYTHON_EXECUTABLE=" + sys.executable,
156
    ],
157
    packages=["my_extension"],
158
    python_requires=">=3.7",
159
)
160
```
161

162
### Advanced Configuration
163

164
```python
165
from skbuild import setup
166
import sys
167

168
def process_manifest(files):
169
    # Custom processing of installed files
170
    return [f for f in files if not f.endswith('.debug')]
171

172
setup(
173
    name="complex_extension", 
174
    version="2.0.0",
175
    cmake_source_dir="native",
176
    cmake_install_dir="lib",
177
    cmake_languages=["C", "CXX", "Fortran"],
178
    cmake_minimum_required_version="3.15",
179
    cmake_process_manifest_hook=process_manifest,
180
    cmake_args=[
181
        "-DCMAKE_BUILD_TYPE=Release",
182
        "-DENABLE_OPTIMIZATIONS=ON",
183
        f"-DPYTHON_EXECUTABLE={sys.executable}",
184
    ],
185
    cmake_with_sdist=True,
186
    packages=["complex_extension"],
187
    package_data={"complex_extension": ["*.so", "*.dll", "*.dylib"]},
188
)
189
```
190

191
### Command-Line Argument Handling
192

193
```python
194
from skbuild import parse_args, setup
195

196
# Parse command-line arguments
197
remaining_args, cmake_exe, skip_test, cmake_args, build_args = parse_args()
198

199
setup(
200
    name="my_package",
201
    cmake_args=cmake_args,
202
    # ... other setup arguments
203
)
204
```