Skip to content

Commit 8cef018

Browse files
jasonGtgjasonGtg
committed
Release v1.8.0: Multi-Python Build System with Automated Distribution
1 parent 59b6910 commit 8cef018

29 files changed

+1341
-98
lines changed

‎.gitignore‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,13 @@ __pycache__/
4545
GSPy_*.txt
4646
*_Test_log.txt
4747

48-
# Development scripts
49-
build_*.bat
48+
# Test executables
49+
tests/*.exe
50+
test_*.exe
51+
52+
# Development scripts (but keep build_and_distribute.bat)
5053
copy_*.bat
54+
tests/test_build.bat
5155
*.cmake
5256
CMakeFiles/
5357
CMakeCache.txt

‎.kiro/specs/multi-python-build-system/design.md‎

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
# Design Document: Multi-Python Build System
2+
3+
## Overview
4+
5+
This design implements a flexible, maintainable build system for the GSPy project that supports multiple Python versions (3.11 and 3.14) through Visual Studio Property Sheets. The solution replaces hard-coded Python paths with reusable configuration files, enabling rapid switching between Python targets while maintaining build integrity.
6+
7+
## Architecture
8+
9+
### Current State Analysis
10+
11+
The existing GSPy.vcxproj file contains:
12+
- Hard-coded Python 3.13/3.14 paths in x64 configurations
13+
- Environment variable-based paths (PYTHON_HOME) in Win32 configurations
14+
- Inconsistent Python library references across configurations
15+
- Mixed approaches that create maintenance complexity
16+
17+
### Target Architecture
18+
19+
The new architecture will use a layered configuration approach:
20+
21+
```
22+
GSPy.vcxproj (Clean, no Python paths)
23+
↓
24+
Property Sheets Layer
25+
├── python_311.props (Python 3.11 configuration)
26+
├── python_314.props (Python 3.14 configuration)
27+
└── [future versions...]
28+
↓
29+
Visual Studio Build System
30+
```
31+
32+
## Components and Interfaces
33+
34+
### 1. Clean Project File (GSPy.vcxproj)
35+
36+
**Purpose**: Contains only core project configuration without Python-specific settings
37+
38+
**Key Changes**:
39+
- Remove all hard-coded Python include paths
40+
- Remove all hard-coded Python library paths
41+
- Remove all hard-coded Python library dependencies
42+
- Maintain existing preprocessor definitions and compiler settings
43+
- Preserve ImportGroup sections for Property Sheet integration
44+
45+
### 2. Python Version Property Sheets
46+
47+
#### python_311.props
48+
**Purpose**: Contains all Python 3.11 specific build configuration
49+
50+
**Configuration Elements**:
51+
```xml
52+
<AdditionalIncludeDirectories>
53+
- $(PYTHON_3_11_HOME)\include
54+
- $(PYTHON_3_11_HOME)\Lib\site-packages\numpy\_core\include
55+
</AdditionalIncludeDirectories>
56+
57+
<AdditionalLibraryDirectories>
58+
- $(PYTHON_3_11_HOME)\libs
59+
</AdditionalLibraryDirectories>
60+
61+
<AdditionalDependencies>
62+
- python311.lib
63+
</AdditionalDependencies>
64+
```
65+
66+
#### python_314.props
67+
**Purpose**: Contains all Python 3.14 specific build configuration
68+
69+
**Configuration Elements**:
70+
```xml
71+
<AdditionalIncludeDirectories>
72+
- $(PYTHON_3_14_HOME)\include
73+
- $(PYTHON_3_14_HOME)\Lib\site-packages\numpy\_core\include
74+
</AdditionalIncludeDirectories>
75+
76+
<AdditionalLibraryDirectories>
77+
- $(PYTHON_3_14_HOME)\libs
78+
</AdditionalLibraryDirectories>
79+
80+
<AdditionalDependencies>
81+
- python314.lib
82+
</AdditionalDependencies>
83+
```
84+
85+
### 3. Property Manager Integration
86+
87+
**Interface**: Visual Studio Property Manager window
88+
- Provides GUI for adding/removing Property Sheets
89+
- Enables rapid switching between Python configurations
90+
- Maintains configuration state per build type (Debug/Release x64)
91+
92+
## Data Models
93+
94+
### Property Sheet Structure
95+
96+
```xml
97+
<?xml version="1.0" encoding="utf-8"?>
98+
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
99+
<ImportGroup Label="PropertySheets" />
100+
<PropertyGroup Label="UserMacros" />
101+
<PropertyGroup />
102+
<ItemDefinitionGroup>
103+
<ClCompile>
104+
<AdditionalIncludeDirectories>
105+
$(PYTHON_X_XX_HOME)\include;
106+
$(PYTHON_X_XX_HOME)\Lib\site-packages\numpy\_core\include;
107+
%(AdditionalIncludeDirectories)
108+
</AdditionalIncludeDirectories>
109+
</ClCompile>
110+
<Link>
111+
<AdditionalLibraryDirectories>
112+
$(PYTHON_X_XX_HOME)\libs;
113+
%(AdditionalLibraryDirectories)
114+
</AdditionalLibraryDirectories>
115+
<AdditionalDependencies>pythonXXX.lib;%(AdditionalDependencies)</AdditionalDependencies>
116+
</Link>
117+
</ItemDefinitionGroup>
118+
<ItemGroup />
119+
</Project>
120+
```
121+
122+
### Environment Variables
123+
124+
**Required System Environment Variables**:
125+
- `PYTHON_3_11_HOME`: Path to Python 3.11 installation (e.g., `C:\Users\[User]\AppData\Local\Programs\Python\Python311`)
126+
- `PYTHON_3_14_HOME`: Path to Python 3.14 installation (e.g., `C:\Users\[User]\AppData\Local\Programs\Python\Python314`)
127+
128+
**Benefits of Environment Variable Approach**:
129+
- **Team Portability**: Works regardless of username or installation path
130+
- **Flexibility**: Supports custom Python installation locations
131+
- **Maintainability**: Single point of configuration per developer
132+
- **Build Server Compatibility**: Easy to configure in CI/CD environments
133+
134+
### Configuration Matrix
135+
136+
| Build Config | Platform | Property Sheet | Python Version | Library |
137+
|--------------|----------|----------------|----------------|---------|
138+
| Debug | x64 | python_311.props | 3.11 | python311.lib |
139+
| Release | x64 | python_311.props | 3.11 | python311.lib |
140+
| Debug | x64 | python_314.props | 3.14 | python314.lib |
141+
| Release | x64 | python_314.props | 3.14 | python314.lib |
142+
143+
## Error Handling
144+
145+
### Build-Time Error Prevention
146+
147+
1. **Missing Property Sheet Detection**
148+
- Build will fail cleanly if no Python Property Sheet is applied
149+
- Clear error messages indicating missing Python configuration
150+
151+
2. **Path Validation**
152+
- Property Sheets contain absolute paths that must exist
153+
- Build system will report missing Python installations clearly
154+
155+
3. **Library Mismatch Prevention**
156+
- Each Property Sheet ensures correct Python library version
157+
- Eliminates runtime errors from version mismatches
158+
159+
### Runtime Error Handling
160+
161+
1. **Python Version Verification**
162+
- GSPy code should verify Python version at runtime
163+
- Graceful handling of version compatibility issues
164+
165+
2. **Dependency Validation**
166+
- Verify NumPy availability and version compatibility
167+
- Clear error messages for missing dependencies
168+
169+
## Testing Strategy
170+
171+
### Build Verification Tests
172+
173+
1. **Clean Build Test**
174+
- Verify project builds successfully with each Property Sheet
175+
- Test both Debug and Release configurations
176+
- Validate output DLL functionality
177+
178+
2. **Switch Test**
179+
- Test rapid switching between Python versions
180+
- Verify build integrity after multiple switches
181+
- Measure switch time (target: <10 seconds)
182+
183+
3. **Configuration Matrix Test**
184+
- Build all combinations of Debug/Release with each Python version
185+
- Verify correct library linking for each combination
186+
- Test output compatibility with target Python versions
187+
188+
### Integration Tests
189+
190+
1. **Python Runtime Tests**
191+
- Load GSPy DLL in Python 3.11 environment
192+
- Load GSPy DLL in Python 3.14 environment
193+
- Verify all exported functions work correctly
194+
- Test NumPy integration for each version
195+
196+
2. **Regression Tests**
197+
- Ensure existing functionality remains intact
198+
- Test all example projects with new build system
199+
- Verify performance characteristics unchanged
200+
201+
### User Experience Tests
202+
203+
1. **Developer Workflow Tests**
204+
- Time measurement for Python version switching
205+
- Usability testing of Property Manager interface
206+
- Documentation accuracy verification
207+
208+
2. **New Developer Onboarding**
209+
- Test setup process for new team members
210+
- Verify documentation clarity and completeness
211+
- Validate troubleshooting procedures
212+
213+
## Implementation Phases
214+
215+
### Phase 1: Project Cleanup
216+
- Remove hard-coded Python paths from GSPy.vcxproj
217+
- Verify project structure remains intact
218+
- Test that build fails cleanly without Python configuration
219+
220+
### Phase 2: Environment Setup and Property Sheet Creation
221+
- Document required environment variables (PYTHON_3_11_HOME, PYTHON_3_14_HOME)
222+
- Create python_311.props with environment variable-based configuration
223+
- Create python_314.props with environment variable-based configuration
224+
- Test individual Property Sheet functionality with environment variables
225+
226+
### Phase 3: Integration and Testing
227+
- Integrate Property Sheets with project configurations
228+
- Perform comprehensive build testing
229+
- Validate switching workflow
230+
231+
### Phase 4: Documentation and Team Setup
232+
- Create user documentation with environment variable setup instructions
233+
- Document team onboarding process for new developers
234+
- Create troubleshooting guide for common environment issues
235+
- Optimize switching process for speed
236+
237+
## Future Extensibility
238+
239+
### Additional Python Versions
240+
- Template-based approach for new Python versions
241+
- Automated Property Sheet generation scripts
242+
- Version detection and validation utilities
243+
244+
### Cross-Platform Considerations
245+
- Property Sheet approach is Windows/Visual Studio specific
246+
- Future Linux/macOS support would require different approach
247+
- Consider CMake integration for cross-platform builds
248+
249+
### Advanced Features
250+
- Automated Python installation detection and environment variable setup
251+
- Build configuration validation scripts
252+
- PowerShell scripts for rapid environment variable configuration
253+
- Integration with package managers for Python version management

‎.kiro/specs/multi-python-build-system/requirements.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Requirements Document
2+
3+
## Introduction
4+
5+
This feature implements a flexible build system for the GSPy project that supports targeting multiple Python versions (3.11 and 3.14) through Visual Studio Property Sheets. The current build system has hard-coded Python paths in the .vcxproj file, making it brittle, error-prone, and difficult to maintain when switching between Python versions.
6+
7+
## Glossary
8+
9+
- **GSPy_Project**: The main Visual Studio C++ project that builds the GSPy DLL
10+
- **Property_Sheet**: A Visual Studio .props file that contains reusable build configuration settings
11+
- **Python_Target_Version**: The specific Python version (3.11 or 3.14) that the build system should target
12+
- **Build_Configuration**: The Visual Studio build configuration (Debug/Release) combined with platform (x64)
13+
- **Python_Include_Paths**: Directory paths containing Python header files and NumPy core includes
14+
- **Python_Library_Paths**: Directory paths containing Python library files for linking
15+
- **Build_Switch_Time**: The time required to change from one Python target version to another
16+
17+
## Requirements
18+
19+
### Requirement 1
20+
21+
**User Story:** As a developer, I want to remove hard-coded Python paths from the main project file, so that the build system is more maintainable and less error-prone.
22+
23+
#### Acceptance Criteria
24+
25+
1. THE GSPy_Project SHALL contain no hard-coded Python version-specific paths in the .vcxproj file
26+
2. THE GSPy_Project SHALL contain no hard-coded Python library references in the .vcxproj file
27+
3. THE GSPy_Project SHALL contain no hard-coded NumPy include paths in the .vcxproj file
28+
4. WHEN the .vcxproj file is examined, THE GSPy_Project SHALL show only Property_Sheet references for Python configuration
29+
5. THE GSPy_Project SHALL maintain all existing build functionality after path removal
30+
31+
### Requirement 2
32+
33+
**User Story:** As a developer, I want to create Property Sheets for each Python version, so that I can easily switch between Python targets without manual path editing.
34+
35+
#### Acceptance Criteria
36+
37+
1. THE GSPy_Project SHALL support a Property_Sheet for Python 3.11 configuration
38+
2. THE GSPy_Project SHALL support a Property_Sheet for Python 3.14 configuration
39+
3. WHEN a Property_Sheet is applied, THE GSPy_Project SHALL include all necessary Python_Include_Paths for the target version
40+
4. WHEN a Property_Sheet is applied, THE GSPy_Project SHALL include all necessary Python_Library_Paths for the target version
41+
5. WHEN a Property_Sheet is applied, THE GSPy_Project SHALL include the correct Python library dependency for linking
42+
43+
### Requirement 3
44+
45+
**User Story:** As a developer, I want to quickly switch between Python versions during build, so that I can efficiently test and deploy for multiple Python environments.
46+
47+
#### Acceptance Criteria
48+
49+
1. WHEN switching Python_Target_Version, THE GSPy_Project SHALL complete the switch within 10 seconds
50+
2. THE GSPy_Project SHALL allow switching between Python versions through Property Manager interface
51+
3. WHEN a Property_Sheet is removed, THE GSPy_Project SHALL cleanly remove all associated Python configuration
52+
4. WHEN a new Property_Sheet is added, THE GSPy_Project SHALL apply all configuration settings correctly
53+
5. THE GSPy_Project SHALL maintain build integrity after Python version switches
54+
55+
### Requirement 4
56+
57+
**User Story:** As a developer, I want the build system to work for both Debug and Release configurations, so that I can develop and deploy using any Python version.
58+
59+
#### Acceptance Criteria
60+
61+
1. THE GSPy_Project SHALL support Property_Sheet application to Debug x64 Build_Configuration
62+
2. THE GSPy_Project SHALL support Property_Sheet application to Release x64 Build_Configuration
63+
3. WHEN applied to any Build_Configuration, THE Property_Sheet SHALL provide complete Python environment setup
64+
4. THE GSPy_Project SHALL build successfully for both Debug and Release with any supported Python_Target_Version
65+
5. THE GSPy_Project SHALL produce correct output binaries for each Build_Configuration and Python_Target_Version combination
66+
67+
### Requirement 5
68+
69+
**User Story:** As a developer, I want clear documentation and guidance for using the new build system, so that other team members can easily adopt and use the multi-Python build process.
70+
71+
#### Acceptance Criteria
72+
73+
1. THE GSPy_Project SHALL include documentation explaining Property_Sheet usage
74+
2. THE GSPy_Project SHALL include step-by-step instructions for switching Python versions
75+
3. THE GSPy_Project SHALL include troubleshooting guidance for common build issues
76+
4. WHEN documentation is followed, THE GSPy_Project SHALL build successfully for new users
77+
5. THE GSPy_Project SHALL include examples of typical development workflows using the new system

0 commit comments

Comments
 (0)