Skip to content

Commit ece7917

Browse files
undefinederrorundefinederror
committed
added .deb package build
1 parent 2acc150 commit ece7917

23 files changed

Lines changed: 1187 additions & 214 deletions

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
upk.code-workspace
2-
__pycache__
2+
__pycache__
3+
*.deb

‎DEB_PACKAGING.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# UPK DEB Packaging Guide
2+
3+
This guide explains how to build a DEB package for UPK (Ubuntu Package Kit) using PyInstaller to create a standalone executable.
4+
5+
## Overview
6+
7+
The packaging process creates a Python package and packages it into a DEB file that can be installed on Ubuntu/Debian systems. This approach has several advantages:
8+
9+
- **Small package size**: Only includes source code and metadata (~30KB)
10+
- **System integration**: Uses system Python and dependencies
11+
- **Easy installation**: Users can install with `sudo dpkg -i upk-{version}.deb`
12+
- **CLI-optimized**: No desktop integration (suitable for command-line tools)
13+
- **Maintainable**: Standard Python package structure
14+
15+
## Prerequisites
16+
17+
- Python 3.10 or higher
18+
- pip
19+
- dpkg-deb (usually pre-installed on Ubuntu/Debian)
20+
21+
## Building the DEB Package
22+
23+
### Quick Start
24+
25+
1. Make the build script executable:
26+
```bash
27+
chmod +x build.sh
28+
```
29+
30+
2. Run the build script:
31+
```bash
32+
./build.sh
33+
```
34+
35+
3. Install the package:
36+
```bash
37+
sudo dpkg -i upk-{version}.deb
38+
```
39+
40+
### What the Build Script Does
41+
42+
1. **Copies source files** to the proper Python package structure
43+
2. **Creates a wrapper script** that executes the Python module
44+
3. **Creates the DEB package structure** with proper directory layout
45+
4. **Generates package metadata** including control file and documentation
46+
5. **Builds the final DEB package** using dpkg-deb
47+
48+
## Package Contents
49+
50+
The resulting DEB package includes:
51+
52+
- **Executable**: `/usr/bin/upk` - The main UPK application
53+
- **Documentation**: `/usr/share/doc/upk/` - Package documentation and license
54+
- **Post-installation script**: Handles setup tasks after installation
55+
56+
## Package Dependencies
57+
58+
### Runtime Dependencies
59+
- `python3 (>= 3.10)` - Python interpreter (for compatibility)
60+
- `python3-click (>= 8.1.0)` - Command-line interface library
61+
- `python3-rich (>= 13.0.0)` - Rich text formatting library
62+
63+
### Recommended Packages
64+
- `apt` - APT package manager
65+
- `snapd` - Snap package manager
66+
- `flatpak` - Flatpak package manager
67+
- `pacstall` - Pacstall package manager
68+
- `am` - AppMan package manager
69+
70+
## Installation
71+
72+
### Install the Package
73+
```bash
74+
sudo dpkg -i upk-{version}.deb
75+
```
76+
77+
### Fix Missing Dependencies (if needed)
78+
```bash
79+
sudo apt install -f
80+
```
81+
82+
### Verify Installation
83+
```bash
84+
upk --help
85+
```
86+
87+
88+
## Uninstallation
89+
90+
```bash
91+
sudo dpkg -r upk
92+
```
93+
94+
## Package Structure
95+
96+
```
97+
upk-debian/
98+
├── DEBIAN/
99+
│ ├── control # Package metadata
100+
│ ├── postinst # Post-installation script
101+
│ └── postrm # Post-removal script
102+
├── usr/
103+
│ ├── bin/
104+
│ │ └── upk # Main executable
105+
│ └── share/
106+
│ └── doc/
107+
│ └── upk/ # Documentation
108+
│ ├── changelog.Debian
109+
│ ├── copyright
110+
│ └── README.Debian
111+
```
112+
113+
## Troubleshooting
114+
115+
### Build Script Issues
116+
117+
**PyInstaller not found**: The script automatically creates a virtual environment and installs PyInstaller.
118+
119+
**Missing dependencies**: The script installs click and rich dependencies in the virtual environment.
120+
121+
**Permission errors**: Ensure you're not running as root during the build process.
122+
123+
### Installation Issues
124+
125+
**Missing dependencies**: Run `sudo apt install -f` to install missing dependencies.
126+
127+
**Architecture mismatch**: The package is built for amd64 architecture. For other architectures, you'll need to build on the target system.
128+
129+
### Runtime Issues
130+
131+
**Executable not found**: Ensure the package was installed correctly with `which upk`.
132+
133+
**Missing system tools**: Install recommended packages for full functionality:
134+
```bash
135+
sudo apt install apt snapd flatpak pacstall
136+
```
137+
138+
## Customization
139+
140+
### Package Metadata
141+
142+
Edit the following in `build.sh`:
143+
144+
- **Maintainer information**: Update the maintainer name and email in the control file
145+
- **Package version**: Modify the version number
146+
- **Description**: Update the package description
147+
- **Dependencies**: Adjust dependencies based on your requirements
148+
149+
### Build Configuration
150+
151+
- **PyInstaller options**: Modify PyInstaller flags in the build command
152+
- **Included files**: Update the `--add-data` flags to include additional files
153+
- **Package structure**: Modify the directory structure as needed
154+
155+
## Development
156+
157+
### Testing the Build Process
158+
159+
1. Clean previous builds:
160+
```bash
161+
rm -f upk-{version}.deb dist/upk build/ -rf
162+
```
163+
164+
2. Rebuild:
165+
```bash
166+
./build.sh
167+
```
168+
169+
3. Test installation in a clean environment or virtual machine
170+
171+
### Debugging
172+
173+
- **PyInstaller warnings**: Check the build output for any warnings
174+
- **Package contents**: Use `dpkg-deb --contents upk-{version}.deb` to verify contents
175+
- **Installation logs**: Check system logs during installation
176+
177+
## Security Considerations
178+
179+
- The executable is self-contained and doesn't require additional Python packages
180+
- The post-installation script runs with root privileges during installation
181+
- All dependencies are bundled, reducing attack surface from external packages
182+
183+
## Performance
184+
185+
- **Package size**: ~30KB (source code only)
186+
- **Startup time**: Standard Python startup time
187+
- **Memory usage**: Standard Python memory usage
188+
- **Dependencies**: Uses system-installed packages
189+
190+
## Support
191+
192+
For issues with the DEB package:
193+
194+
1. Check the troubleshooting section above
195+
2. Verify your system meets the requirements
196+
3. Test with a clean installation
197+
4. Report issues with build output and system information
198+
199+
## License
200+
201+
The DEB packaging scripts and documentation are provided under the same license as the main UPK project.

‎MANIFEST.in‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
include README.md
2+
include LICENSE
3+
recursive-include backends *.py

‎README.md‎

Lines changed: 51 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,15 @@ Enter the number of the package to install (or 'q' to cancel):
1919

2020
## Features
2121

22-
- 🔍 **Search packages** across all configured backends
23-
- ⬇️ **Install packages** with source selection
22+
- 🔍 **Search packages** across all configured backends with live progress
23+
- ⬇️ **Install packages** with interactive source selection
24+
- 📦 **Install local files** - supports `.deb` and `.AppImage` files
25+
- 🌐 **Install remote files** - download and install from URLs
2426
- 🔄 **Update package lists** and upgrade packages
2527
- 🗑️ **Remove packages** with automatic source detection
26-
- ⚙️ **Configuration system** for customizing behavior
2728
- 📋 **List installed packages** with filtering options
28-
29+
- ⚙️ **Configuration system** for customizing behavior
30+
- 🎯 **Exact match searching** to find specific packages
2931

3032
## Available Backends
3133

@@ -35,7 +37,7 @@ Enter the number of the package to install (or 'q' to cancel):
3537
| Snap | `snap` | Yes | Canonical's package system |
3638
| Flatpak | `flatpak` | Yes | Cross-distro package format |
3739
| Pacstall | `pacstall` | Yes | AUR-like package manager |
38-
| AppImage | N/A | Yes | Portable application format |
40+
| AppImage | `am` | Yes | [Application Manager](https://github.com/ivan-hc/AM) by ivan-hc |
3941

4042
**Note**: Backends are automatically disabled if their required command isn't found.
4143

@@ -44,17 +46,10 @@ Enter the number of the package to install (or 'q' to cancel):
4446
### Prerequisites
4547
- Python 3.10+
4648
- Ubuntu-based system
47-
- Recommended: [Nala](https://gitlab.com/volian/nala) (`sudo apt install nala`)
49+
- Optional: [Nala](https://gitlab.com/volian/nala) (`sudo apt install nala`) for faster APT operations
4850

4951
### Install UPK
50-
```bash
51-
git clone https://github.com/undefinederror/upk
52-
cd upk
53-
pip install -e .
54-
# optional but recommended
55-
# add an alias in your ~/.bash_aliases
56-
alias upk='python3 /path/to/upk/upk.py'
57-
52+
Grab the .deb file from [releases](https://github.com/undefinederror/upk/releases)
5853
```
5954
6055
## Configuration
@@ -70,24 +65,54 @@ upk config set disabled_backends '["snap"]'
7065
# Enable exact match searching
7166
upk config set always_exact_search true
7267
68+
# Disable interactive prompts
69+
upk config set interactive_prompts false
70+
7371
# List all configurations
7472
upk config list
73+
74+
# Get a specific config value
75+
upk config get backends_priority
7576
```
7677

78+
### Configuration Options
79+
80+
| Option | Type | Default | Description |
81+
|--------|------|---------|-------------|
82+
| `backends_priority` | list | `["apt", "flatpak", "snap", "pacstall"]` | Order to prioritize backends in search results |
83+
| `disabled_backends` | list | `[]` | List of backends to disable |
84+
| `always_exact_search` | bool | `false` | Only show exact matches in search |
85+
| `interactive_prompts` | bool | `true` | Enable interactive prompts for package selection |
86+
| `path_downloads` | string | `~/.local/share/upk/downloads` | Directory for downloaded files |
87+
| `path_appimages` | string | `~/.local/share/applications/AppImages` | Directory for AppImages |
88+
7789
## Usage Examples
7890

7991
```bash
8092
# Search for packages
8193
upk search firefox
8294

83-
# Search for packages, exact match
95+
# Search for packages, exact match only
8496
upk search firefox -e
8597

86-
# Install Firefox, follow prompt and choose source
98+
# Install Firefox (prompts to choose source)
8799
upk install firefox
88100

89-
# Install Firefox via specific backend
90-
upk install firefox --source flatpak
101+
# Install Firefox, exact match only
102+
upk install firefox -e
103+
104+
# Install Firefox with extra args for backend (e.g., --classic for snap)
105+
# Use -- to separate extra_args from options
106+
upk install firefox -- --classic
107+
108+
# Install a local .deb file
109+
upk install ./my-package.deb
110+
111+
# Install a local .AppImage file
112+
upk install ./my-app.AppImage
113+
114+
# Install a remote file from URL
115+
upk install https://example.com/my-app.AppImage
91116

92117
# Update package lists
93118
upk update
@@ -101,11 +126,16 @@ upk upgrade firefox
101126
# Remove package
102127
upk remove firefox
103128

104-
# List installed packages
129+
# List all installed packages
105130
upk list
106-
```
107131

132+
# List installed packages with filter
133+
upk list firefox
134+
135+
# List installed packages, exact match
136+
upk list firefox -e
137+
```
108138

109139
## License
110140

111-
MIT License - see [LICENSE](LICENSE) for details.
141+
MIT License - see [LICENSE](LICENSE) for details.

‎VERSION‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
1.0.0

0 commit comments

Comments
 (0)