Skip to content

Commit f48c3ab

Browse files
author
glitches
committed
Add build instructions for all platforms
1 parent 7c6feb4 commit f48c3ab

File tree

1 file changed

+281
-0
lines changed

1 file changed

+281
-0
lines changed

‎BUILD_INSTRUCTIONS.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
# Build Instructions for All Platforms
2+
3+
This document provides instructions for building portable executables for Linux, Windows, and macOS.
4+
5+
## Prerequisites
6+
7+
- Python 3.10+ installed
8+
- All dependencies from `requirements.txt`
9+
- PyInstaller: `pip install pyinstaller`
10+
11+
---
12+
13+
## Linux (AppImage)
14+
15+
### Quick Build
16+
17+
```bash
18+
# Install dependencies
19+
pip install -r requirements.txt
20+
pip install pyinstaller
21+
22+
# Build the executable
23+
pyinstaller --clean datamosh-gui.spec
24+
25+
# Download appimagetool
26+
cd AppImage
27+
wget https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage
28+
chmod +x appimagetool-x86_64.AppImage
29+
30+
# Build AppImage
31+
ARCH=x86_64 ./appimagetool-x86_64.AppImage Datamosh-GUI.AppDir Datamosh-GUI-x86_64.AppImage
32+
```
33+
34+
### Result
35+
- **File**: `Datamosh-GUI-x86_64.AppImage` (~103 MB)
36+
- **Usage**: `chmod +x Datamosh-GUI-x86_64.AppImage && ./Datamosh-GUI-x86_64.AppImage`
37+
- **Compatible**: Most Linux distributions (Ubuntu, Fedora, Arch, etc.)
38+
39+
---
40+
41+
## Windows (Standalone EXE)
42+
43+
### Prerequisites (on Windows)
44+
- Python 3.10+ from python.org
45+
- Visual C++ Redistributable (usually included)
46+
47+
### Build Steps
48+
49+
```powershell
50+
# Install dependencies
51+
pip install -r requirements.txt
52+
pip install pyinstaller
53+
54+
# Build standalone EXE
55+
pyinstaller --onefile --windowed --name "Datamosh-GUI" `
56+
--icon=datamosh-gui.ico `
57+
--add-data "README.md;." `
58+
--add-data "LICENSE;." `
59+
--hidden-import=PIL._tkinter_finder `
60+
--hidden-import=tkinterdnd2 `
61+
--hidden-import=cv2 `
62+
mosh_gui.py
63+
64+
# Or use the spec file
65+
pyinstaller --clean datamosh-gui-windows.spec
66+
```
67+
68+
### Windows Spec File (datamosh-gui-windows.spec)
69+
70+
```python
71+
# -*- mode: python ; coding: utf-8 -*-
72+
block_cipher = None
73+
74+
a = Analysis(
75+
['mosh_gui.py'],
76+
pathex=[],
77+
binaries=[],
78+
datas=[('README.md', '.'), ('LICENSE', '.')],
79+
hiddenimports=['PIL._tkinter_finder', 'tkinterdnd2', 'cv2'],
80+
hookspath=[],
81+
hooksconfig={},
82+
runtime_hooks=[],
83+
excludes=['matplotlib', 'numpy.testing', 'scipy', 'pandas'],
84+
win_no_prefer_redirects=False,
85+
win_private_assemblies=False,
86+
cipher=block_cipher,
87+
noarchive=False,
88+
)
89+
90+
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
91+
92+
exe = EXE(
93+
pyz,
94+
a.scripts,
95+
a.binaries,
96+
a.zipfiles,
97+
a.datas,
98+
[],
99+
name='Datamosh-GUI',
100+
debug=False,
101+
bootloader_ignore_signals=False,
102+
strip=False,
103+
upx=True,
104+
upx_exclude=[],
105+
runtime_tmpdir=None,
106+
console=False,
107+
disable_windowed_traceback=False,
108+
target_arch=None,
109+
codesign_identity=None,
110+
entitlements_file=None,
111+
icon='datamosh-gui.ico' # Optional: add icon file
112+
)
113+
```
114+
115+
### Result
116+
- **File**: `dist/Datamosh-GUI.exe` (~150-200 MB)
117+
- **Usage**: Double-click to run
118+
- **Compatible**: Windows 10/11 (64-bit)
119+
120+
---
121+
122+
## macOS (App Bundle / DMG)
123+
124+
### Prerequisites (on macOS)
125+
- Python 3.10+ (preferably from python.org, not Homebrew)
126+
- Xcode Command Line Tools: `xcode-select --install`
127+
128+
### Build Steps
129+
130+
```bash
131+
# Install dependencies
132+
pip3 install -r requirements.txt
133+
pip3 install pyinstaller
134+
135+
# Build .app bundle
136+
pyinstaller --onefile --windowed --name "Datamosh GUI" \
137+
--add-data "README.md:." \
138+
--add-data "LICENSE:." \
139+
--hidden-import=PIL._tkinter_finder \
140+
--hidden-import=tkinterdnd2 \
141+
--hidden-import=cv2 \
142+
--osx-bundle-identifier=com.glitches.datamosh-gui \
143+
mosh_gui.py
144+
145+
# Or use the spec file
146+
pyinstaller --clean datamosh-gui-macos.spec
147+
```
148+
149+
### Create DMG (optional)
150+
151+
```bash
152+
# Install create-dmg
153+
brew install create-dmg
154+
155+
# Create DMG
156+
create-dmg \
157+
--volname "Datamosh GUI" \
158+
--window-pos 200 120 \
159+
--window-size 600 400 \
160+
--icon-size 100 \
161+
--icon "Datamosh GUI.app" 175 120 \
162+
--hide-extension "Datamosh GUI.app" \
163+
--app-drop-link 425 120 \
164+
"Datamosh-GUI-macOS.dmg" \
165+
"dist/Datamosh GUI.app"
166+
```
167+
168+
### macOS Spec File (datamosh-gui-macos.spec)
169+
170+
```python
171+
# -*- mode: python ; coding: utf-8 -*-
172+
block_cipher = None
173+
174+
a = Analysis(
175+
['mosh_gui.py'],
176+
pathex=[],
177+
binaries=[],
178+
datas=[('README.md', '.'), ('LICENSE', '.')],
179+
hiddenimports=['PIL._tkinter_finder', 'tkinterdnd2', 'cv2'],
180+
hookspath=[],
181+
hooksconfig={},
182+
runtime_hooks=[],
183+
excludes=['matplotlib', 'numpy.testing', 'scipy', 'pandas'],
184+
win_no_prefer_redirects=False,
185+
win_private_assemblies=False,
186+
cipher=block_cipher,
187+
noarchive=False,
188+
)
189+
190+
pyz = PYZ(a.pure, a.zipped_data, cipher=block_cipher)
191+
192+
exe = EXE(
193+
pyz,
194+
a.scripts,
195+
a.binaries,
196+
a.zipfiles,
197+
a.datas,
198+
[],
199+
name='Datamosh GUI',
200+
debug=False,
201+
bootloader_ignore_signals=False,
202+
strip=False,
203+
upx=True,
204+
upx_exclude=[],
205+
runtime_tmpdir=None,
206+
console=False,
207+
disable_windowed_traceback=False,
208+
target_arch=None,
209+
codesign_identity=None,
210+
entitlements_file=None,
211+
)
212+
213+
app = BUNDLE(
214+
exe,
215+
name='Datamosh GUI.app',
216+
icon=None, # Optional: add icon file
217+
bundle_identifier='com.glitches.datamosh-gui',
218+
info_plist={
219+
'NSPrincipalClass': 'NSApplication',
220+
'NSHighResolutionCapable': 'True',
221+
},
222+
)
223+
```
224+
225+
### Result
226+
- **File**: `dist/Datamosh GUI.app` or `Datamosh-GUI-macOS.dmg`
227+
- **Usage**: Drag to Applications folder, then launch
228+
- **Compatible**: macOS 10.15+ (Catalina and newer)
229+
230+
---
231+
232+
## File Sizes (Approximate)
233+
234+
| Platform | Format | Size | Notes |
235+
|----------|--------|------|-------|
236+
| Linux | AppImage | ~103 MB | Includes OpenCV, PIL, all deps |
237+
| Windows | EXE | ~150-200 MB | Single executable, no install |
238+
| macOS | App/DMG | ~120-180 MB | Native .app bundle |
239+
240+
---
241+
242+
## Troubleshooting
243+
244+
### Missing ffmpeg
245+
The executables don't include ffmpeg. Users need to install it separately:
246+
247+
**Linux**: `sudo apt install ffmpeg`
248+
**Windows**: Download from ffmpeg.org and add to PATH
249+
**macOS**: `brew install ffmpeg`
250+
251+
### Python not found (Windows)
252+
- Install Python from python.org (not Microsoft Store version)
253+
- Check "Add Python to PATH" during installation
254+
255+
### Permission denied (Linux/macOS)
256+
```bash
257+
chmod +x Datamosh-GUI-x86_64.AppImage # Linux
258+
chmod +x dist/Datamosh\ GUI.app/Contents/MacOS/Datamosh\ GUI # macOS
259+
```
260+
261+
### Gatekeeper warning (macOS)
262+
```bash
263+
# Allow unsigned app
264+
sudo xattr -r -d com.apple.quarantine dist/Datamosh\ GUI.app
265+
```
266+
267+
---
268+
269+
## Cross-Platform Build (Advanced)
270+
271+
For building all platforms from a single machine, consider:
272+
273+
1. **GitHub Actions** - Automated builds for all platforms
274+
2. **Docker** - Build Linux versions in containers
275+
3. **Wine** - Build Windows EXE on Linux (experimental)
276+
277+
---
278+
279+
## Contributing
280+
281+
If you successfully build for a platform not covered here, please contribute to this document!

0 commit comments

Comments
 (0)