Skip to content

Commit afb856c

Browse files
jwaisnerjwaisner
authored
Merge pull request #10 from Bearsampp/gradle-convert
gradle-convert
2 parents 5eaf05c + 0c19ff5 commit afb856c

File tree

16 files changed

+2449
-101
lines changed

16 files changed

+2449
-101
lines changed

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,8 @@
1515

1616
# Qodo
1717
/.qodo
18+
19+
# Gradle
20+
.gradle/
21+
build/
22+
.gradle-cache/

‎.gradle-docs/BUILD.md‎

Lines changed: 307 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,307 @@
1+
# Build Documentation for module-phpmyadmin
2+
3+
## Overview
4+
5+
This module uses a pure Gradle build system. The build process downloads phpMyAdmin releases, configures them, and packages them for Bearsampp.
6+
7+
## Build Structure
8+
9+
### Version Folder Inclusion
10+
11+
When building a release, the build system **includes the version folder** in the compressed archive. This is consistent with other Bearsampp modules (e.g., module-bruno, module-php).
12+
13+
**Example structure in the final archive:**
14+
```
15+
phpmyadmin5.2.1/
16+
├── bearsampp.conf
17+
├── config.inc.php
18+
├── index.php
19+
└── [phpMyAdmin files]
20+
```
21+
22+
### How It Works
23+
24+
1. **Bundle Folder Naming**: The bundle folder is derived from the bundle path and includes the version:
25+
- Example: `phpmyadmin5.2.1`
26+
27+
2. **Preparation Directory**: Files are copied to `${bundleTmpPrepPath}/${bundleName}${bundleVersion}`:
28+
- This creates: `tmp/bundles_prep/apps/phpmyadmin/phpmyadmin5.2.1/[files]`
29+
30+
3. **Compression**: The build system compresses from the parent directory, preserving the version folder:
31+
- Archive contains: `phpmyadmin5.2.1/` as the root directory
32+
33+
### Build Process Flow
34+
35+
1. **Version Validation**: Checks if the specified version exists in `bin/` or `bin/archived/` directory
36+
2. **Preparation**: Creates temporary directory structure with version folder name
37+
3. **Download**: Fetches phpMyAdmin from:
38+
- modules-untouched repository (primary)
39+
- releases.properties (fallback)
40+
- Standard URL format (final fallback)
41+
4. **Extraction**: Extracts phpMyAdmin archive using 7-Zip
42+
5. **Configuration**: Copies custom configuration files from `bin/[version]/`
43+
6. **Build Copy**: Copies to bundles_build directory (uncompressed for development/testing)
44+
7. **Archiving**: Creates 7z archive with version folder included
45+
8. **Hashing**: Generates MD5, SHA1, SHA256, and SHA512 hash files
46+
47+
## Building a Release
48+
49+
### Using Gradle
50+
51+
```bash
52+
# Build a specific version (interactive mode)
53+
gradle release
54+
55+
# Build a specific version (non-interactive mode)
56+
gradle release -PbundleVersion=5.2.1
57+
58+
# Build all available versions
59+
gradle releaseAll
60+
61+
# List available versions
62+
gradle listVersions
63+
64+
# Verify build environment
65+
gradle verify
66+
67+
# Display build information
68+
gradle info
69+
```
70+
71+
## Version Management
72+
73+
### Supported Versions
74+
75+
Versions are defined in `releases.properties` and can also be fetched from the modules-untouched repository. Each entry maps a version to its download URL:
76+
77+
```properties
78+
5.2.1 = https://files.phpmyadmin.net/phpMyAdmin/5.2.1/phpMyAdmin-5.2.1-all-languages.7z
79+
5.2.0 = https://files.phpmyadmin.net/phpMyAdmin/5.2.0/phpMyAdmin-5.2.0-all-languages.7z
80+
```
81+
82+
### Version Folder Structure
83+
84+
Each version has its own folder in `bin/` or `bin/archived/`:
85+
86+
```
87+
bin/
88+
├── phpmyadmin5.2.1/
89+
│ ├── bearsampp.conf
90+
│ └── config.inc.php
91+
├── phpmyadmin5.2.0/
92+
│ ├── bearsampp.conf
93+
│ └── config.inc.php
94+
└── archived/
95+
└── phpmyadmin4.9.10/
96+
├── bearsampp.conf
97+
└── config.inc.php
98+
```
99+
100+
## Configuration Files
101+
102+
### build.properties
103+
104+
Main build configuration:
105+
106+
```properties
107+
bundle.name = phpmyadmin
108+
bundle.release = 2025.1.23
109+
bundle.type = apps
110+
bundle.format = 7z
111+
```
112+
113+
### releases.properties
114+
115+
Maps versions to download URLs for phpMyAdmin releases. This serves as a local fallback when the modules-untouched repository is unavailable.
116+
117+
## Archive Format
118+
119+
The final archive (`.7z` format by default) contains:
120+
121+
```
122+
phpmyadmin[VERSION]/
123+
├── bearsampp.conf # Bearsampp configuration
124+
├── config.inc.php # phpMyAdmin configuration
125+
├── index.php # phpMyAdmin entry point
126+
├── libraries/ # phpMyAdmin libraries
127+
├── themes/ # phpMyAdmin themes
128+
└── [all phpMyAdmin files] # Complete phpMyAdmin installation
129+
```
130+
131+
## Comparison with Other Modules
132+
133+
This build structure is consistent with other Bearsampp modules:
134+
135+
- **module-bruno**: Uses pure Gradle build with version folder inclusion
136+
- **module-php**: Uses pure Gradle build with version folder inclusion
137+
- **module-apache**: Uses similar pattern with version folder inclusion
138+
139+
All modules ensure the version folder is included in the compressed archive for proper organization and version management within Bearsampp.
140+
141+
## Key Features
142+
143+
### Pure Gradle Implementation
144+
145+
- No external dependencies required (except 7-Zip for compression)
146+
- Modern build system with caching and incremental builds
147+
- Parallel execution support
148+
- Better IDE integration
149+
150+
### Automatic Download
151+
152+
The build system automatically downloads phpMyAdmin releases from:
153+
1. **modules-untouched repository** (primary source)
154+
2. **releases.properties** (local fallback)
155+
3. **Standard URL format** (final fallback)
156+
157+
### Version Folder Inclusion
158+
159+
**Critical**: The build system ensures the version folder is included in the archive. This is verified by:
160+
- Creating prep directory with version folder: `tmp/bundles_prep/apps/phpmyadmin/phpmyadmin5.2.1/`
161+
- Archiving from parent directory to include folder structure
162+
- Final archive contains: `phpmyadmin5.2.1/[files]`
163+
164+
This matches the pattern used in module-bruno and module-php, ensuring proper integration with Bearsampp.
165+
166+
### Interactive and Non-Interactive Modes
167+
168+
The build system supports both interactive and non-interactive modes:
169+
170+
**Interactive Mode**:
171+
```bash
172+
gradle release
173+
```
174+
- Displays a menu of available versions
175+
- Allows selection by index or version string
176+
- Shows version locations (bin/ or bin/archived/)
177+
178+
**Non-Interactive Mode**:
179+
```bash
180+
gradle release -PbundleVersion=5.2.1
181+
```
182+
- Directly builds the specified version
183+
- Suitable for CI/CD pipelines
184+
- No user interaction required
185+
186+
### Build All Versions
187+
188+
Build all available versions with a single command:
189+
```bash
190+
gradle releaseAll
191+
```
192+
- Builds all versions found in bin/ and bin/archived/
193+
- Provides summary of successful and failed builds
194+
- Continues on error to build remaining versions
195+
196+
## Troubleshooting
197+
198+
### Version Folder Not Found
199+
200+
If you get an error about a missing version folder:
201+
202+
1. Check that the version exists in `bin/` or `bin/archived/`:
203+
```bash
204+
gradle listVersions
205+
```
206+
207+
2. Verify the version is defined in `releases.properties` or modules-untouched:
208+
```bash
209+
gradle listReleases
210+
```
211+
212+
3. Create the version folder structure:
213+
```bash
214+
mkdir bin/phpmyadmin[VERSION]
215+
# Add bearsampp.conf and config.inc.php
216+
```
217+
218+
### Build Environment Issues
219+
220+
Run the verification task to check your environment:
221+
222+
```bash
223+
gradle verify
224+
```
225+
226+
This checks for:
227+
- Java 8+ installation
228+
- Required build files (build.properties)
229+
- bin/ directory existence
230+
- 7-Zip installation
231+
232+
### Archive Structure Verification
233+
234+
To verify the version folder is included in the archive:
235+
236+
```bash
237+
# List archive contents
238+
7z l bearsampp-phpmyadmin-5.2.1-2025.1.23.7z
239+
240+
# Should show:
241+
# phpmyadmin5.2.1/
242+
# phpmyadmin5.2.1/index.php
243+
# phpmyadmin5.2.1/config.inc.php
244+
# etc.
245+
```
246+
247+
### Download Issues
248+
249+
If phpMyAdmin download fails:
250+
251+
1. Check network connectivity
252+
2. Verify the version exists in modules-untouched:
253+
```bash
254+
gradle checkModulesUntouched
255+
```
256+
3. Add the version to `releases.properties` as a fallback
257+
4. The build system will automatically try multiple sources
258+
259+
### 7-Zip Not Found
260+
261+
If 7-Zip is not found:
262+
263+
1. Install 7-Zip from https://www.7-zip.org/
264+
2. Or set the `7Z_HOME` environment variable to your 7-Zip installation directory
265+
3. Verify installation:
266+
```bash
267+
gradle verify
268+
```
269+
270+
## Build Output Structure
271+
272+
### Temporary Build Files
273+
274+
Located in `bearsampp-build/tmp/`:
275+
276+
```
277+
bearsampp-build/tmp/
278+
├── downloads/phpmyadmin/ # Downloaded archives (cached)
279+
│ └── phpMyAdmin-5.2.1-all-languages.7z
280+
├── extract/phpmyadmin/ # Temporary extraction
281+
│ └── 5.2.1/
282+
├── bundles_prep/apps/phpmyadmin/ # Prepared bundles
283+
│ └── phpmyadmin5.2.1/
284+
└── bundles_build/apps/phpmyadmin/ # Final uncompressed output
285+
└── phpmyadmin5.2.1/
286+
```
287+
288+
### Final Archives
289+
290+
Located in `bearsampp-build/apps/phpmyadmin/{bundle.release}/`:
291+
292+
```
293+
bearsampp-build/apps/phpmyadmin/2025.1.23/
294+
├── bearsampp-phpmyadmin-5.2.1-2025.1.23.7z
295+
├── bearsampp-phpmyadmin-5.2.1-2025.1.23.7z.md5
296+
├── bearsampp-phpmyadmin-5.2.1-2025.1.23.7z.sha1
297+
├── bearsampp-phpmyadmin-5.2.1-2025.1.23.7z.sha256
298+
└── bearsampp-phpmyadmin-5.2.1-2025.1.23.7z.sha512
299+
```
300+
301+
## References
302+
303+
- [Bearsampp Project](https://github.com/bearsampp/bearsampp)
304+
- [module-bruno build.gradle](https://github.com/Bearsampp/module-bruno/blob/gradle-convert/build.gradle) - Reference implementation
305+
- [module-php build.gradle](https://github.com/Bearsampp/module-php/blob/gradle-convert/build.gradle) - Reference implementation
306+
- [phpMyAdmin Official Site](https://www.phpmyadmin.net/)
307+
- [Gradle Documentation](https://docs.gradle.org/)

0 commit comments

Comments
 (0)