Skip to content

Commit d8e9f97

Browse files
gcclinuxgcclinux
committed
Add comprehensive build documentation to Jekyll site
1 parent 2a63599 commit d8e9f97

24 files changed

+2897
-61
lines changed

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,3 +69,6 @@ Thumbs.db
6969
# If you want to preserve certain jars or packages, whitelist them explicitly.
7070
# Example: to keep packages/SmallTextPad_1.4.5.jar unignored, add:
7171
# !/packages/SmallTextPad_1.4.5.jar
72+
73+
Gemfile
74+
Gemfile.lock

‎docs/README-jar.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
layout: default
3+
title: JAR Build Guide - SmallTextPad
4+
---
5+
6+
[← Back to Home](index.html)
7+
8+
# JAR Build for SmallTextPad
9+
10+
This guide covers building the standalone JAR file for SmallTextPad, a lightweight Java text editor with encryption and multi-language support.
11+
12+
## Files
13+
14+
- `build-jar.sh` - Script to compile sources and build the standalone JAR file
15+
- `README-jar.md` - This documentation file
16+
17+
## Prerequisites
18+
19+
### System Requirements
20+
- Java 21+ JDK installed
21+
- Standard Unix tools (bash, find)
22+
23+
### Installing Build Dependencies
24+
25+
**Fedora/RHEL/CentOS:**
26+
```bash
27+
sudo dnf install java-21-openjdk-devel
28+
```
29+
30+
**Ubuntu/Debian:**
31+
```bash
32+
sudo apt install openjdk-21-jdk
33+
```
34+
35+
**openSUSE:**
36+
```bash
37+
sudo zypper install java-21-openjdk-devel
38+
```
39+
40+
**macOS:**
41+
```bash
42+
brew install openjdk@21
43+
```
44+
45+
## Building the JAR File
46+
47+
The build script can be run from anywhere in the project:
48+
49+
### From Project Root:
50+
```bash
51+
./packaging/build-jar.sh
52+
```
53+
54+
### From Packaging Directory:
55+
```bash
56+
cd packaging
57+
./build-jar.sh
58+
```
59+
60+
The script will:
61+
1. Navigate to the project root automatically
62+
2. Delete any existing compiled class files
63+
3. Generate a list of all Java source files
64+
4. Compile all Java sources to the `bin/` directory
65+
5. Copy resource bundles (`.properties` files) to the correct package structure
66+
6. Copy image resources to the JAR root for classpath access
67+
7. Copy dictionary files for spell-checking
68+
8. Create the JAR file with proper manifest
69+
9. Test launch the application
70+
71+
## Build Output
72+
73+
After successful build:
74+
- **JAR file:** `classes/artifacts/SmallTextPad.jar`
75+
- **Compiled classes:** `bin/` directory
76+
- **Source list:** `sources.txt` (generated during build)
77+
78+
## Running the JAR
79+
80+
### Direct Execution:
81+
```bash
82+
java -jar classes/artifacts/SmallTextPad.jar
83+
```
84+
85+
### With File Argument:
86+
```bash
87+
java -jar classes/artifacts/SmallTextPad.jar /path/to/file.txt
88+
```
89+
90+
### Using Desktop Environment:
91+
On systems with desktop integration, you can double-click the JAR file if `.jar` files are associated with Java.
92+
93+
## JAR Contents
94+
95+
The JAR file includes:
96+
- **Compiled classes:** All Java classes in proper package structure
97+
- **Resource bundles:** Language files (English, Dutch, Polish, Portuguese)
98+
- `wagemaker/co/uk/lang/LabelsBundle_*.properties`
99+
- **Images:** Application icons and toolbar images at JAR root
100+
- `about.png`, `copy.png`, `cut.png`, `paste.png`, etc.
101+
- **Dictionaries:** Spell-check dictionaries
102+
- `dic/Dictionary_en.txt`
103+
- `dic/Dictionary_nl.txt`
104+
- **Manifest:** Proper Main-Class definition for executable JAR
105+
106+
## Distribution
107+
108+
The generated JAR is a fully self-contained executable that can be:
109+
- Copied to any system with Java 21+ installed
110+
- Distributed via download links
111+
- Included in other packaging formats (RPM, DEB, Snap, etc.)
112+
- Run without installation
113+
114+
## Troubleshooting
115+
116+
### Build Fails - javac not found:
117+
Ensure Java JDK is installed and `javac` is in your PATH:
118+
```bash
119+
which javac
120+
javac -version
121+
```
122+
123+
### Application Doesn't Launch:
124+
Verify Java runtime is installed:
125+
```bash
126+
java -version
127+
```
128+
129+
### Missing Resources Error:
130+
If you see `MissingResourceException` or `NullPointerException` for resources:
131+
1. Clean and rebuild:
132+
```bash
133+
rm -rf bin/ classes/artifacts/
134+
./packaging/build-jar.sh
135+
```
136+
2. Verify JAR contents:
137+
```bash
138+
jar tf classes/artifacts/SmallTextPad.jar | grep -E "(\.properties$|\.png$)"
139+
```
140+
141+
### Permission Denied:
142+
Make the script executable:
143+
```bash
144+
chmod +x packaging/build-jar.sh
145+
```
146+
147+
## Development Workflow
148+
149+
For rapid development and testing:
150+
151+
1. **Edit source files** in `src/` directory
152+
2. **Run build script** to compile and test:
153+
```bash
154+
./packaging/build-jar.sh
155+
```
156+
3. **Application launches automatically** for testing
157+
4. **Close application** and repeat as needed
158+
159+
The script automatically cleans previous builds, so you always get a fresh compile.
160+
161+
## Notes
162+
163+
- The build script uses `set -euo pipefail` to exit immediately on any error
164+
- Deprecation warnings during compilation are enabled with `-Xlint:deprecation`
165+
- The script supports being run from any directory - it automatically finds the project root
166+
- The JAR manifest specifies `wagemaker.co.uk.main.Launcher` as the Main-Class
167+
168+
## See Also
169+
170+
- [RPM Build Guide](README-rpm.html) - Building RPM packages for Fedora/RHEL/openSUSE
171+
- [Snap Build Guide](README-snap.html) - Building Snap packages for universal Linux distribution
172+
- [Windows Build Guide](README-windows.html) - Building Windows installers and portable packages
173+
- [Back to Home](index.html) - Main documentation and downloads

packaging/README-rpm.md renamed to docs/README-rpm.md

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
1+
---
2+
layout: default
3+
title: RPM Build Guide - SmallTextPad
4+
---
5+
6+
[← Back to Home](index.html)
7+
18
# RPM Packaging for SmallTextPad
29

3-
This directory contains the RPM packaging files for SmallTextPad, a lightweight Java text editor with encryption and multi-language support.
10+
This guide covers building RPM packages for SmallTextPad, a lightweight Java text editor with encryption and multi-language support.
411

512
## Files
613

@@ -160,4 +167,11 @@ To contribute improvements to the RPM packaging:
160167

161168
- **Project Repository:** https://github.com/gcclinux/smalltextpad
162169
- **Issues:** https://github.com/gcclinux/smalltextpad/issues
163-
- **Latest Releases:** https://github.com/gcclinux/smalltextpad/releases/latest
170+
- **Latest Releases:** https://github.com/gcclinux/smalltextpad/releases/latest
171+
172+
## See Also
173+
174+
- [JAR Build Guide](README-jar.html) - Building standalone JAR files
175+
- [Snap Build Guide](README-snap.html) - Building Snap packages for universal Linux distribution
176+
- [Windows Build Guide](README-windows.html) - Building Windows installers and portable packages
177+
- [Back to Home](index.html) - Main documentation and downloads

0 commit comments

Comments
 (0)