85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
# LibreOffice AutoSave Extension
|
|
|
|
A lightweight, background-running extension for LibreOffice that automatically saves your documents while you work. Built with modern Python and packaged using Poetry.
|
|
|
|
## Features
|
|
|
|
- **Silent & Automatic:** Hooks into LibreOffice's global `OnLoad` and `OnNew` events to run completely in the background without needing a user interface.
|
|
- **Smart Debouncing:** Waits for you to pause typing (default: 1 second delay) before issuing a save. Rapid continuous typing will dynamically delay the save loop to prevent UI stuttering on large documents.
|
|
- **Atomic Backups:** Before triggering LibreOffice's internal synchronous `.store()`, the extension executes an atomic file-copy of the last known saved state to a hidden `.bak` file (e.g., `.filename.bak`). This protects your data payload from corruption if your OS or LibreOffice crashes during a complex write cycle.
|
|
- **Safe Evaluation:** Will not blindly save new documents that have not been given an initial file path location, protecting you from unexpected file generation.
|
|
|
|
## Automatic Installation
|
|
|
|
**For Windows (PowerShell):**
|
|
```powershell
|
|
# Download the latest release
|
|
Invoke-WebRequest -Uri "https://github.com/JMR-dev/LibreOfficeAutoSave/releases/latest/download/AutoSave.oxt" -OutFile "AutoSave.oxt"
|
|
|
|
# Install the extension
|
|
& "C:\Program Files\LibreOffice\program\unopkg.com" add -f AutoSave.oxt
|
|
|
|
# Clean up the downloaded file
|
|
Remove-Item AutoSave.oxt
|
|
```
|
|
|
|
**For macOS / Linux (Bash):**
|
|
```bash
|
|
# Download the latest release
|
|
curl -LO https://github.com/JMR-dev/LibreOfficeAutoSave/releases/latest/download/AutoSave.oxt
|
|
|
|
# Install the extension
|
|
if [[ "$OSTYPE" == "darwin"* ]]; then
|
|
/Applications/LibreOffice.app/Contents/MacOS/unopkg add -f AutoSave.oxt
|
|
else
|
|
unopkg add -f AutoSave.oxt
|
|
fi
|
|
|
|
# Clean up the downloaded file
|
|
rm AutoSave.oxt
|
|
```
|
|
|
|
## Manual Installation
|
|
|
|
1. Grab the compiled `AutoSave.oxt` file from the `dist/` directory or the latest release.
|
|
2. Open LibreOffice.
|
|
3. Navigate to **Tools > Extension Manager**.
|
|
4. Click **Add...** and select `AutoSave.oxt`.
|
|
5. Restart LibreOffice. The listener is now globally attached and will silently watch your documents!
|
|
|
|
## Development & Testing
|
|
|
|
This repository uses [Poetry](https://python-poetry.org/) to handle dev dependencies, unit testing, and linting. Note that the runtime execution of the extension happens within LibreOffice's embedded Python interpreter.
|
|
|
|
### Setup
|
|
```bash
|
|
# Initialize the virtual environment and install pytest
|
|
poetry install
|
|
```
|
|
|
|
### Running Tests
|
|
The test suite utilizes `unittest.mock` to heavily mock the internal PyUNO C++ bridge. You can run the test matrix without needing an active LibreOffice instance:
|
|
```bash
|
|
poetry run pytest
|
|
```
|
|
|
|
### Fast Deployment Loop
|
|
To accelerate iteration speed when modifying the python codebase, use the provided deployment scripts. They will automatically build the ZIP archive, forcefully kill active LibreOffice instances to drop file locks, use the `unopkg` command-line utility to uninstall the old extension, and inject the freshly built `.oxt` before restarting Writer.
|
|
|
|
**For Windows (PowerShell):**
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File .\deploy_and_test.ps1
|
|
```
|
|
|
|
**For macOS / Linux (Bash):**
|
|
```bash
|
|
chmod +x deploy_and_test.sh
|
|
./deploy_and_test.sh
|
|
```
|
|
|
|
## Debugging
|
|
|
|
If the AutoSave functionality fails silently, check the output log generated by the background thread. The extension writes timestamps and tracebacks directly to your home directory:
|
|
- **Windows:** `C:\Users\YourUsername\workspace\LibreOfficeAutoSave\autosave_debug.log`
|
|
- **Linux/Mac:** `~/autosave_debug.log`
|