Jellypie-todo install.sh rationale

install_rationale.txt

 This install.sh script uses a hybrid approach that combines virtual           
  environment isolation with system-wide deployment.                                         
                              
  The Script's Approach       
                              
  Key characteristics:        
                              
  1. System-wide venv with system site packages (line 149):                                  
  sudo $PYTHON -m venv --system-site-packages "$VENV_PATH"                                   
    - Creates venv at /opt/jollpi-venv                                                       
    - The --system-site-packages flag allows the venv to access system-installed packages    
  (PyGObject, GTK4, GtkSourceView5)                                                          
  2. Install with --no-deps (line 151):                                                      
  sudo "$VENV_PATH/bin/pip" install --no-deps .                                              
    - Only installs the application itself, not its dependencies                             
    - Dependencies are expected to come from system packages                                 
  3. System integration:      
    - Creates symlink in /usr/local/bin (line 153)                                           
    - Installs desktop file, icons, and GTK style scheme to system directories (lines        
  156-158)                    
  4. Distribution-aware dependency checking (lines 27-142):                                  
    - Detects distro type and uses appropriate package manager                               
    - Automatically installs missing system dependencies                                     
                              
  Comparison to Other Approaches                                                             
                              
  1. Traditional System Package Installation (deb/rpm)                                       
                              
  # Debian/Ubuntu             
  sudo apt install my-app     
                              
  # Fedora                    
  sudo dnf install my-app     
                              
  Pros:                       
  - Fully integrated with system package manager                                             
  - Dependency resolution handled automatically                                              
  - Easy updates via package manager                                                         
  - System-wide availability  
                              
  Cons:                       
  - Requires packaging for each distro                                                       
  - Slower to release updates (packaging overhead)                                           
  - Limited to distro's Python version                                                       
  - More complex build pipeline                                                              
                              
  Comparison: This script mimics system packaging benefits without requiring actual package  
  creation.                   
                              
  2. pip User Install (--user flag)                                                          
                              
  pip install --user my-app   
                              
  Pros:                       
  - No root required          
  - Per-user isolation        
  - Simple installation       
                              
  Cons:                       
  - Doesn't handle non-Python dependencies (GTK4, etc.)                                      
  - Binary goes to ~/.local/bin (may not be in PATH)                                         
  - Desktop integration requires manual steps                                                
  - Each user needs separate installation                                                    
                              
  Comparison: The script's approach is system-wide vs per-user, and handles system           
  dependencies automatically. 
                              
  3. pipx (Isolated app environment)                                                         
                              
  pipx install my-app         
                              
  Pros:                       
  - Each app in isolated venv 
  - No dependency conflicts   
  - Automatic PATH setup      
  - Per-user installation     
                              
  Cons:                       
  - Can't easily share system packages (PyGObject)                                           
  - Larger disk usage (duplicate dependencies)                                               
  - Doesn't handle system dependencies                                                       
  - No desktop file integration out-of-box                                                   
                              
  Comparison: The script's --system-site-packages approach is crucial here. PyGObject can't  
  be pip-installed easily, so sharing system packages is necessary.                          
                              
  4. Plain venv (Manual)      
                              
  python3 -m venv myenv       
  source myenv/bin/activate   
  pip install my-app          
                              
  Pros:                       
  - Full control over environment                                                            
  - Project-specific dependencies                                                            
  - Reproducible builds       
                              
  Cons:                       
  - User must manage activation                                                              
  - No system integration     
  - Manual PATH setup         
  - Doesn't handle system dependencies                                                       
                              
  Comparison: The script automates this and adds system integration, but loses the           
  development flexibility.    
                              
  5. Flatpak/Snap (Containerized apps)                                                       
                              
  flatpak install my-app      
  snap install my-app         
                              
  Pros:                       
  - Sandboxed security        
  - Bundle all dependencies   
  - Cross-distro compatibility
  - Automatic updates         
                              
  Cons:                       
  - Larger download size (bundled runtime)                                                   
  - More startup time         
  - Complexity in build configuration                                                        
  - Restricted filesystem access                                                             
                              
  Comparison: The script's approach is much lighter-weight and integrates more tightly with  
  the system.                 
                             
           
  Why This Approach Makes Sense for Jellypie                                                 
                              
  The script's hybrid approach is well-suited for GTK/Python applications because:           
                              
  1. GTK dependencies must be system-installed - PyGObject, GTK4, and GtkSourceView5 are     
  difficult/impossible to pip-install                                                        
  2. Avoids polluting system Python - Uses isolated venv at /opt                             
  3. System-wide availability - Installed once, available to all users                       
  4. Desktop integration - Properly installs .desktop files and icons                        
  5. Distribution-aware - Handles different package managers automatically                   
                              
  Trade-offs                  
                              
  Advantages:                 
  - Clean separation from system Python                                                      
  - Access to system GTK libraries                                                           
  - Proper desktop integration
  - Single installation for all users                                                        
  - Automatic dependency installation                                                        
                              
  Disadvantages:              
  - Requires root/sudo        
  - Less portable than Flatpak/Snap                                                          
  - Tied to system Python version                                                            
  - Manual uninstall required (no package manager tracking)                                  
  - Updates require re-running script (not integrated with system updates)                   
                              
  Summary                     
                              
  This approach is a pragmatic middle ground for GTK Python applications that:               
  - Need system GTK libraries (--system-site-packages)                                       
  - Want isolation from system Python (venv at /opt)                                         
  - Require desktop integration (.desktop files, icons)                                      
  - Should be system-wide but aren't worth full package maintenance                          
                              
  It's more sophisticated than basic pip install, but lighter-weight than full distribution  
  packaging or containerization.                                                             


Details
  The key operation is:
  sudo "$VENV_PATH/bin/pip" install --no-deps .
  When this command runs, pip:
                              
  1. Reads the package configuration (pyproject.toml:26-27):
  2. Copies Python source files to /opt/jollpi-venv/lib/python3.x/site-packages/jellypie/:   
  3. Creates an entry point wrapper script at /opt/jollpi-venv/bin/jellypie:                 
  4. The symlink (install.sh:153) makes it accessible:                                       
                              
  What Runs When You Type jellypie                                                           
                              
  User types: jellypie        
      ↓                       
  Shell finds: /usr/local/bin/jollpi (symlink)                                               
      ↓                       
  Symlink points to: /opt/jollpi-venv/bin/jollpi (wrapper script)                            
      ↓                       
  Wrapper script runs with: #!/opt/jollpi-venv/bin/python3                                   
      ↓                       
  Python imports: from jellypie.main import main                                             
      ↓                       
  Calls: main() function from src/jellypie/main.py:105                                       
      ↓                       
  Application starts!