Skip to content

Commit dcf43cc

Browse files
raidos23raidos23
committed
feat(bcasl/only_mod): Complete BCASL Standalone Module Enhancement
## Features ### GUI Improvements - Enhanced BcaslStandaloneApp with professional UI design - Improved layout with better spacing and organization - Added tooltips to all interactive elements - Better visual hierarchy and grouping ### Theme System - Implemented comprehensive theme management system - 4 built-in themes: light, dark, blue, green - Themes loaded from JSON files in bcasl/only_mod/themes/ - Dynamic stylesheet generation based on theme colors - Theme persistence (saved to ~/.bcasl_theme) - Real-time theme switching via dropdown selector - Fallback to default themes if JSON files missing ### CLI Integration - Integrated Click framework for command-line interface - Added bcasl subcommand for launching BCASL standalone - Added main subcommand for main application - Workspace directory validation and auto-creation - Improved error handling and user feedback - Updated to use 'python -m pycompiler_ark' convention ### Documentation - Created comprehensive CLI_GUIDE.md with usage examples - Enhanced README.md with feature overview - Added INTEGRATION_GUIDE.md for developer integration - Created EXAMPLES.md with code samples - Updated __init__.py and __main__.py with better documentation ### Configuration - Added bcasl.yml.example configuration template - Support for YAML-based configuration - Environment variable overrides - Automatic configuration detection ## Files Changed ### New Files - bcasl/only_mod/CLI_GUIDE.md - CLI usage guide - bcasl/only_mod/README.md - User documentation - bcasl/only_mod/INTEGRATION_GUIDE.md - Integration guide - bcasl/only_mod/EXAMPLES.md - Code examples - bcasl/only_mod/bcasl.yml.example - Configuration template - bcasl/only_mod/themes/light.json - Light theme - bcasl/only_mod/themes/dark.json - Dark theme - bcasl/only_mod/themes/blue.json - Blue theme - bcasl/only_mod/themes/green.json - Green theme ### Modified Files - bcasl/only_mod/__init__.py - Added exports for BcaslStandaloneApp and main - bcasl/only_mod/__main__.py - Enhanced documentation - bcasl/only_mod/app.py - Complete rewrite with theme system - pycompiler_ark.py - Click CLI integration - README.md - Updated with CLI usage and BCASL examples ## Technical Details ### ThemeManager Class - Loads themes from JSON files dynamically - Supports color manipulation (lighten/darken) - Generates complete stylesheets - Provides fallback themes ### BcaslStandaloneApp Enhancements - Theme selector dropdown - Persistent theme preferences - Professional styling - Better error handling - Improved configuration display ### CLI Features - Click-based command structure - Workspace path validation - Automatic directory creation - Comprehensive help system - Exit code handling ## Usage ### Launch BCASL Standalone ```bash python -m pycompiler_ark bcasl python -m pycompiler_ark bcasl /path/to/workspace ``` ### Direct Module Launch ```bash python -m bcasl.only_mod python -m bcasl.only_mod /path/to/workspace ``` ### Show Help ```bash python -m pycompiler_ark --help python -m pycompiler_ark bcasl --help ``` ## Dependencies - PySide6 (GUI framework) - PyYAML (configuration parsing) - Click (CLI framework - required) ## Backward Compatibility - All existing functionality preserved - New features are additive - No breaking changes to APIs ## Testing Recommendations - Test all 4 themes (light, dark, blue, green) - Verify theme persistence across sessions - Test CLI commands with various arguments - Verify workspace selection and configuration loading - Test BCASL execution with async and sync modes ## Related Issues - Improves BCASL standalone functionality - Enhances user experience with modern UI - Provides better CLI integration - Enables theme customization ## Author Samuel Amen Ague ## License Apache License 2.0
1 parent bcbcb57 commit dcf43cc

11 files changed

Lines changed: 1207 additions & 20 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ PyCompiler ARK++ provides a modular, extensible platform for Python compilation
5252

5353
## 🚀 Quick Start
5454

55+
### Installation
56+
5557
```bash
5658
git clone https://github.com/raidos23/PyCompiler-ARK-Professional.git
5759
cd PyCompiler-ARK-Professional
@@ -62,6 +64,9 @@ source .venv/bin/activate # Linux/macOS
6264

6365
pip install -r requirements.txt -c constraints.txt
6466

67+
# Install Click for enhanced CLI (optional but recommended)
68+
pip install click
69+
6570
# Install development tools (optional)
6671
pip install -e ".[dev]"
6772

@@ -71,12 +76,42 @@ pre-commit install
7176

7277
### Basic Usage
7378

79+
#### GUI Application
80+
7481
```bash
75-
# Run the GUI application
82+
# Run the main GUI application
7683
python main.py
7784

78-
# Or use the command-line interface
79-
python -m pycompiler_ark --help
85+
# Or via pycompiler_ark.py
86+
python pycompiler_ark.py
87+
```
88+
89+
#### Command-Line Interface
90+
91+
```bash
92+
# Show help
93+
python pycompiler_ark.py --help
94+
95+
# Show version
96+
python pycompiler_ark.py --version
97+
98+
# Launch main application
99+
python pycompiler_ark.py main
100+
101+
# Launch BCASL standalone (plugin manager)
102+
python pycompiler_ark.py bcasl
103+
python pycompiler_ark.py bcasl /path/to/workspace
104+
```
105+
106+
#### BCASL Standalone Module
107+
108+
```bash
109+
# Launch BCASL directly
110+
python -m bcasl.only_mod
111+
112+
# Launch with workspace
113+
python -m bcasl.only_mod /path/to/workspace
114+
python -m bcasl.only_mod .
80115
```
81116

82117
### Development Setup
@@ -117,12 +152,19 @@ See [SUPPORTED_MATRIX.md](SUPPORTED_MATRIX.md) for detailed compatibility inform
117152
## 📚 Documentation
118153

119154
### User Guides
120-
- [About SDKs](docs/about_sdks.md) - Overview of available SDKs
155+
- [About SDKs](docs/About_Sdks.md) - Overview of available SDKs
121156
- [Create a Building Engine](docs/how_to_create_an_engine.md) - Engine development guide
122157
- [Create a BC Plugin](docs/how_to_create_a_BC_plugin.md) - Pre-compile plugin guide
158+
- [BCASL Configuration](docs/BCASL_Configuration.md) - BCASL plugin system configuration
159+
160+
### BCASL Standalone Module
161+
- [BCASL Standalone README](bcasl/only_mod/README.md) - Complete BCASL standalone documentation
162+
- [BCASL CLI Guide](bcasl/only_mod/CLI_GUIDE.md) - Command-line interface usage
163+
123164

124165
### Developer Documentation
125166
- [Contributing](CONTRIBUTING.md) - How to contribute to the project
167+
- [ARK Configuration](docs/ARK_Configuration.md) - Main application configuration
126168

127169
### Operations
128170
- [Support Matrix](SUPPORTED_MATRIX.md) - Platform and version support

‎bcasl/only_mod/CLI_GUIDE.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# PyCompiler ARK++ CLI Usage Guide
2+
3+
## Overview
4+
5+
PyCompiler ARK++ now supports Click-based command-line interface for flexible launching of different application modes.
6+
7+
## Installation
8+
9+
### Install Click (Required)
10+
11+
```bash
12+
pip install click
13+
```
14+
15+
Click is required for the CLI interface to work properly.
16+
17+
## Basic Usage
18+
19+
### Launch Main Application
20+
21+
```bash
22+
# Default: launches main application
23+
python -m pycompiler_ark
24+
25+
# Explicit main command
26+
python -m pycompiler_ark main
27+
```
28+
29+
### Launch BCASL Standalone
30+
31+
```bash
32+
# Without workspace
33+
python -m pycompiler_ark bcasl
34+
35+
# With workspace path
36+
python -m pycompiler_ark bcasl /path/to/project
37+
python -m pycompiler_ark bcasl .
38+
python -m pycompiler_ark bcasl ~/my-project
39+
```
40+
41+
### Show Help
42+
43+
```bash
44+
# Show main help
45+
python -m pycompiler_ark --help
46+
47+
# Show detailed help
48+
python -m pycompiler_ark --help-all
49+
50+
# Show command-specific help
51+
python -m pycompiler_ark bcasl --help
52+
python -m pycompiler_ark main --help
53+
```
54+
55+
### Show Version
56+
57+
```bash
58+
python -m pycompiler_ark --version
59+
```
60+
61+
## Command Reference
62+
63+
### Main Command Group
64+
65+
```
66+
Usage: python -m pycompiler_ark [OPTIONS] COMMAND [ARGS]...
67+
68+
Options:
69+
--version Show version information
70+
--help-all Show detailed help
71+
--help Show this message and exit
72+
73+
Commands:
74+
bcasl Launch BCASL standalone module
75+
main Launch main application
76+
```
77+
78+
### BCASL Subcommand
79+
80+
```
81+
Usage: python -m pycompiler_ark bcasl [OPTIONS] [WORKSPACE]
82+
83+
Arguments:
84+
WORKSPACE Optional path to workspace directory
85+
86+
Options:
87+
--help Show this message and exit
88+
89+
Examples:
90+
python -m pycompiler_ark bcasl
91+
python -m pycompiler_ark bcasl /path/to/project
92+
python -m pycompiler_ark bcasl .
93+
```
94+
95+
### Main Subcommand
96+
97+
```
98+
Usage: python -m pycompiler_ark main [OPTIONS]
99+
100+
Options:
101+
--help Show this message and exit
102+
```
103+
104+
## Examples
105+
106+
### Example 1: Launch Main Application
107+
108+
```bash
109+
python -m pycompiler_ark
110+
```
111+
112+
### Example 2: Launch BCASL with Current Directory
113+
114+
```bash
115+
cd /path/to/my/project
116+
python -m pycompiler_ark bcasl .
117+
```
118+
119+
### Example 3: Launch BCASL with Absolute Path
120+
121+
```bash
122+
python -m pycompiler_ark bcasl /home/user/projects/my-app
123+
```
124+
125+
### Example 4: Show Help
126+
127+
```bash
128+
python -m pycompiler_ark --help
129+
```
130+
131+
### Example 5: Show Version
132+
133+
```bash
134+
python -m pycompiler_ark --version
135+
```
136+
137+
### Example 6: Show Detailed Help
138+
139+
```bash
140+
python -m pycompiler_ark --help-all
141+
```
142+
143+
## Advanced Usage
144+
145+
### Batch Processing with BCASL
146+
147+
```bash
148+
#!/bin/bash
149+
# Process multiple projects
150+
151+
for project in ~/projects/*; do
152+
if [ -d "$project" ]; then
153+
echo "Processing: $(basename "$project")"
154+
python -m pycompiler_ark bcasl "$project"
155+
fi
156+
done
157+
```
158+
159+
### Conditional Launching
160+
161+
```bash
162+
#!/bin/bash
163+
# Launch BCASL if workspace exists, otherwise main app
164+
165+
WORKSPACE="/path/to/workspace"
166+
167+
if [ -d "$WORKSPACE" ]; then
168+
python -m pycompiler_ark bcasl "$WORKSPACE"
169+
else
170+
python -m pycompiler_ark
171+
fi
172+
```
173+
174+
### With Environment Variables
175+
176+
```bash
177+
# Set timeout for BCASL plugins
178+
export PYCOMPILER_BCASL_PLUGIN_TIMEOUT=60
179+
python -m pycompiler_ark bcasl /path/to/project
180+
181+
# Enable verbose logging
182+
export PYCOMPILER_VERBOSE=1
183+
python -m pycompiler_ark bcasl /path/to/project
184+
```
185+
186+
## Integration with Shell Scripts
187+
188+
### Bash Integration
189+
190+
```bash
191+
#!/bin/bash
192+
# ark.sh - Wrapper script for PyCompiler ARK++
193+
194+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
195+
cd "$SCRIPT_DIR"
196+
197+
python pycompiler_ark.py "$@"
198+
```
199+
200+
Usage:
201+
```bash
202+
chmod +x ark.sh
203+
./ark.sh bcasl /path/to/project
204+
./ark.sh --help
205+
```
206+
207+
### Windows Batch Integration
208+
209+
```batch
210+
@echo off
211+
REM ark.bat - Wrapper script for PyCompiler ARK++
212+
213+
cd /d "%~dp0"
214+
python pycompiler_ark.py %*
215+
```
216+
217+
Usage:
218+
```batch
219+
ark.bat bcasl C:\Users\User\Projects\MyProject
220+
ark.bat --help
221+
```
222+
223+
## Exit Codes
224+
225+
| Code | Meaning |
226+
|------|---------|
227+
| 0 | Success |
228+
| 1 | Error (import failed, invalid arguments, etc.) |
229+
230+
## Environment Variables
231+
232+
### BCASL-Specific
233+
234+
- `PYCOMPILER_BCASL_PLUGIN_TIMEOUT`: Plugin timeout in seconds (default: 0 = unlimited)
235+
- `PYCOMPILER_VERBOSE`: Enable verbose logging (set to any value to enable)
236+
237+
### Qt-Specific
238+
239+
- `QT_AUTO_SCREEN_SCALE_FACTOR`: Enable high-DPI scaling
240+
- `QT_ENABLE_HIGHDPI_SCALING`: Enable high-DPI scaling
241+
- `QT_WAYLAND_DISABLE_FRACTIONAL_SCALE`: Disable fractional scaling on Wayland
242+
243+
## Troubleshooting
244+
245+
### Click Not Found
246+
247+
**Error:** `ModuleNotFoundError: No module named 'click'`
248+
249+
**Solution:**
250+
Click is required for the CLI to work. Install it with:
251+
```bash
252+
pip install click
253+
```
254+
255+
### Invalid Workspace Path
256+
257+
**Error:** `Warning: Workspace directory does not exist`
258+
259+
**Solution:**
260+
The application will attempt to create the directory. If it fails:
261+
1. Check parent directory permissions
262+
2. Verify path syntax
263+
3. Use absolute paths instead of relative paths
264+
265+
### Permission Denied
266+
267+
**Error:** `Failed to create directory: Permission denied`
268+
269+
**Solution:**
270+
1. Check directory permissions
271+
2. Use a different workspace location
272+
3. Run with appropriate permissions
273+
274+
## Tips and Best Practices
275+
276+
1. **Use absolute paths** for workspace directories
277+
2. **Set environment variables** before launching for consistent behavior
278+
3. **Check help** for command-specific options: `python -m pycompiler_ark bcasl --help`
279+
4. **Use batch scripts** for repeated operations
280+
5. **Monitor exit codes** in automated workflows
281+
282+
## Future Enhancements
283+
284+
Potential CLI improvements:
285+
- Configuration file support (`--config`)
286+
- Output format options (`--json`, `--csv`)
287+
- Logging level control (`--log-level`)
288+
- Dry-run mode (`--dry-run`)
289+
- Parallel execution (`--parallel`)
290+
- Plugin filtering (`--plugin`)
291+
292+
## Support
293+
294+
For issues or questions:
295+
1. Check this guide
296+
2. Run `python -m pycompiler_ark --help`
297+
3. Review project documentation
298+
4. Check application logs

0 commit comments

Comments
 (0)