0
# Platform Integration
1

2
Platform-specific functionality for CMake generator detection, selection, and platform-specific build configuration. Provides abstractions for cross-platform building and platform-specific optimizations.
3

4
## Capabilities
5

6
### Platform Detection
7

8
Function for automatically detecting the current platform and returning appropriate platform-specific functionality.
9

10
```python { .api }
11
def get_platform():
12
    """
13
    Get an instance of CMakePlatform matching the current platform.
14
    
15
    Automatically detects the current operating system and architecture
16
    to return the appropriate platform-specific CMake integration.
17
    
18
    Returns:
19
    CMakePlatform: Platform-specific instance (WindowsPlatform, LinuxPlatform, 
20
                   OSXPlatform, etc.)
21
    """
22
```
23

24
### CMake Generator Management
25

26
Class representing a CMake generator with its configuration, environment variables, and platform-specific settings.
27

28
```python { .api }
29
class CMakeGenerator:
30
    """
31
    Represents a CMake generator configuration.
32
    
33
    Encapsulates generator name, environment variables, toolset specification,
34
    architecture targeting, and additional arguments for platform-specific
35
    CMake generation.
36
    """
37
    
38
    def __init__(
39
        self,
40
        name: str,
41
        env: Mapping[str, str] | None = None,
42
        toolset: str | None = None,
43
        arch: str | None = None,
44
        args: Iterable[str] | None = None,
45
    ) -> None:
46
        """
47
        Initialize CMake generator with configuration.
48
        
49
        Parameters:
50
        - name: CMake generator name (e.g., "Visual Studio 16 2019", "Unix Makefiles")
51
        - env: Environment variables to set during generation
52
        - toolset: Toolset specification for generators that support it
53
        - arch: Architecture specification (x64, Win32, ARM, etc.)
54
        - args: Additional arguments to pass to generator
55
        """
56
```
57

58
### Platform Base Class
59

60
Abstract base class providing common platform functionality and generator management.
61

62
```python { .api }
63
class CMakePlatform:
64
    """
65
    Base class for platform-specific CMake integration.
66
    
67
    Encapsulates platform-specific logic for CMake generator detection,
68
    validation, and selection. Provides methods for testing generator
69
    compatibility and finding the best available generator.
70
    """
71
    
72
    def __init__(self) -> None:
73
        """Initialize platform with default configuration."""
74
    
75
    @property
76
    def default_generators(self) -> list[CMakeGenerator]:
77
        """
78
        List of generators considered for automatic selection.
79
        
80
        Returns:
81
        List of CMakeGenerator objects in priority order
82
        """
83
    
84
    @property 
85
    def generator_installation_help(self) -> str:
86
        """
87
        Return message guiding user for installing valid toolchain.
88
        
89
        Provides platform-specific instructions for installing build
90
        tools and CMake generators.
91
        
92
        Returns:
93
        Help message string with installation instructions
94
        """
95
    
96
    def get_best_generator(
97
        self,
98
        generator_name: str | None = None,
99
        skip_generator_test: bool = False,
100
        languages: Iterable[str] = ("CXX", "C"),
101
        cleanup: bool = True,
102
        cmake_executable: str = CMAKE_DEFAULT_EXECUTABLE,
103
        cmake_args: Iterable[str] = (),
104
        architecture: str | None = None,
105
    ) -> CMakeGenerator:
106
        """
107
        Find working generator by testing configuration and compilation.
108
        
109
        Tests generators in priority order to find one that successfully
110
        configures and compiles a test project with the specified languages.
111
        
112
        Parameters:
113
        - generator_name: Specific generator to test (None for auto-selection)
114
        - skip_generator_test: Skip compilation test (configuration only)
115
        - languages: Programming languages to test (C, CXX, Fortran)
116
        - cleanup: Clean up test directory after testing
117
        - cmake_executable: Path to cmake executable
118
        - cmake_args: Additional CMake arguments for testing
119
        - architecture: Target architecture override
120
        
121
        Returns:
122
        CMakeGenerator object for working generator
123
        
124
        Raises:
125
        SKBuildGeneratorNotFoundError: If no working generator found
126
        """
127
    
128
    def get_generator(self, generator_name: str) -> CMakeGenerator:
129
        """
130
        Get generator by name from default generators list.
131
        
132
        Parameters:
133
        - generator_name: Name of generator to find
134
        
135
        Returns:
136
        CMakeGenerator object matching the name
137
        """
138
    
139
    def get_generators(self, generator_name: str) -> list[CMakeGenerator]:
140
        """
141
        Get all generators matching the given name.
142
        
143
        Parameters:
144
        - generator_name: Name pattern to match
145
        
146
        Returns:
147
        List of CMakeGenerator objects matching the name
148
        """
149
```
150

151
### Test Project Management
152

153
Static methods for managing test projects used in generator validation.
154

155
```python { .api }
156
@staticmethod
157
def write_test_cmakelist(languages: Iterable[str]) -> None:
158
    """
159
    Write minimal CMakeLists.txt for testing language support.
160
    
161
    Creates a test CMake project that validates support for the
162
    specified programming languages.
163
    
164
    Parameters:
165
    - languages: Programming languages to test (C, CXX, Fortran, etc.)
166
    """
167

168
@staticmethod
169
def cleanup_test() -> None:
170
    """
171
    Delete test project directory.
172
    
173
    Removes temporary files and directories created during
174
    generator testing and validation.
175
    """
176
```
177

178
## Usage Examples
179

180
### Basic Platform Detection
181

182
```python
183
from skbuild.platform_specifics import get_platform
184

185
# Get current platform instance
186
platform = get_platform()
187
print(f"Platform: {type(platform).__name__}")
188

189
# Get available generators
190
generators = platform.default_generators
191
for gen in generators:
192
    print(f"Available generator: {gen.name}")
193
```
194

195
### Generator Selection
196

197
```python
198
from skbuild.platform_specifics import get_platform, CMakeGenerator
199

200
platform = get_platform()
201

202
# Automatic generator selection
203
try:
204
    best_gen = platform.get_best_generator(
205
        languages=["C", "CXX"],
206
        skip_generator_test=False
207
    )
208
    print(f"Selected generator: {best_gen.name}")
209
except SKBuildGeneratorNotFoundError:
210
    print("No suitable generator found")
211
    print(platform.generator_installation_help)
212

213
# Manual generator selection
214
try:
215
    specific_gen = platform.get_generator("Unix Makefiles")
216
    print(f"Found generator: {specific_gen.name}")
217
except:
218
    print("Unix Makefiles not available on this platform")
219
```
220

221
### Custom Generator Configuration
222

223
```python
224
from skbuild.platform_specifics import CMakeGenerator
225

226
# Create custom generator with specific configuration
227
custom_gen = CMakeGenerator(
228
    name="Visual Studio 16 2019",
229
    env={"CC": "cl.exe", "CXX": "cl.exe"},
230
    toolset="v142",
231
    arch="x64",
232
    args=["-T", "host=x64"]
233
)
234

235
# Use in platform selection
236
platform = get_platform()
237
try:
238
    best_gen = platform.get_best_generator(
239
        generator_name=custom_gen.name,
240
        architecture="x64"
241
    )
242
    print(f"Using custom generator: {best_gen.name}")
243
except SKBuildGeneratorNotFoundError as e:
244
    print(f"Custom generator failed: {e}")
245
```
246

247
### Cross-Platform Generator Handling
248

249
```python
250
from skbuild.platform_specifics import get_platform
251
import sys
252

253
platform = get_platform()
254

255
# Platform-specific generator preferences
256
if sys.platform == "win32":
257
    preferred_generators = ["Visual Studio 16 2019", "Visual Studio 15 2017"]
258
elif sys.platform == "darwin":
259
    preferred_generators = ["Xcode", "Unix Makefiles"]
260
else:
261
    preferred_generators = ["Unix Makefiles", "Ninja"]
262

263
# Try generators in preference order
264
selected_generator = None
265
for gen_name in preferred_generators:
266
    try:
267
        generator = platform.get_best_generator(
268
            generator_name=gen_name,
269
            skip_generator_test=True  # Quick check
270
        )
271
        selected_generator = generator
272
        break
273
    except SKBuildGeneratorNotFoundError:
274
        continue
275

276
if selected_generator:
277
    print(f"Using generator: {selected_generator.name}")
278
else:
279
    print("No preferred generators available")
280
    print(platform.generator_installation_help)
281
```
282

283
### Generator Testing and Validation
284

285
```python
286
from skbuild.platform_specifics import get_platform, CMakePlatform
287

288
platform = get_platform()
289

290
# Test generator with specific languages
291
test_languages = ["C", "CXX", "Fortran"]
292

293
try:
294
    # Write test project
295
    CMakePlatform.write_test_cmakelist(test_languages)
296
    
297
    # Test generator
298
    working_gen = platform.get_best_generator(
299
        languages=test_languages,
300
        cleanup=False  # Keep test files for inspection
301
    )
302
    
303
    print(f"Generator {working_gen.name} supports: {', '.join(test_languages)}")
304
    
305
finally:
306
    # Always cleanup
307
    CMakePlatform.cleanup_test()
308
```