296 lines
11 KiB
Markdown
296 lines
11 KiB
Markdown
# dir-odt-to-pdf
|
||
|
||
<img src="resources/icon/app/web/icon-192.png" alt="Dir ODT to PDF" width="120" height="auto">
|
||
|
||
## Convert source directory with **odt** files to target path with **pdf** files
|
||
|
||
> [!NOTE]
|
||
> Source files will be converted if are changed or not exist in target path
|
||
|
||
> [!TIP]
|
||
> This is for a real customer need <br>
|
||
> It has been make with [cursor](https://www.cursor.com/) and some AI agents. <br>
|
||
> A way to create MacOS App by running a Rust binary (all via build automation tool to control the build process of a project, etc.)
|
||
|
||
## Table of Contents
|
||
- [Overview](#overview)
|
||
- [Repository Content](#repository-content)
|
||
- [MacOS APP](#macos-app)
|
||
- [Terminal Commands](#terminal-commands)
|
||
- [Basic Usage](#basic-usage)
|
||
- [Options](#options)
|
||
- [Examples](#examples)
|
||
- [Log Levels](#log-levels)
|
||
- [Notes](#notes)
|
||
- [Settings](#settings)
|
||
- [Just](#just)
|
||
- [Recipes](#recipes)
|
||
- [Main Values](#main-values)
|
||
- [For Development](#for-development)
|
||
- [For tests](#for-tests)
|
||
- [To work on app](#to-work-on-app)
|
||
|
||
## Overview
|
||
|
||
The following extensions will be converted via LibreOffice **soffice** command.
|
||
|
||
**FILES_TO_CONVERT**: odt, doc, docx
|
||
|
||
The following extensions or path will be copied to **target** with any conversion
|
||
|
||
**FILES_TO_COPY**: jpg, jpeg, png, gif, bmp, tiff, webp, avif, txt, md
|
||
|
||
The following path will be ignored during [clean_target_directory](src/directory_processor.rs) process after <u>coversions</u> and <u>copy</u> tasks
|
||
|
||
**PATHS_TO_IGNORE**: .DS_Store, .syncthing, .sync-conflict-, .stfolder, .stversions
|
||
|
||
## Repository Content
|
||
|
||
<pre>
|
||
.
|
||
├── Cargo.lock
|
||
├── Cargo.toml Rust Cargo defs
|
||
├── justfile File defs for just command
|
||
├── linux Files to pack app for Linux
|
||
│ ├── install.sh Installer command (app and bin)
|
||
│ └── README README for linux installation
|
||
├── macos
|
||
│ ├── dir-odt-to-pdf.scpt Apple Script to build APP
|
||
│ ├── DirOdtToPdf.app Apple app
|
||
│ ├── install.command DMG Installer command (app and bin)
|
||
│ └── README DMG README
|
||
├── packages Distribution Packages
|
||
│ └── DirOdtToPdf.dmg DMG file
|
||
├── README.md
|
||
├── resources
|
||
│ ├── icon
|
||
│ ├── icon.psd
|
||
│ ├── ins_background.png
|
||
│ └── tools
|
||
├── run.sh Script model to run
|
||
├── src Rust source code
|
||
│ ├── directory_processor.rs
|
||
│ ├── error.rs
|
||
│ ├── file_type.rs
|
||
│ ├── lib.rs
|
||
│ ├── logging.rs
|
||
│ ├── main.rs
|
||
│ ├── tests Unitary tests
|
||
│ ├── tests.rs
|
||
│ └── tools.rs
|
||
├── tests Integration tests
|
||
│ ├── common.rs
|
||
│ ├── logging_writer_tests.rs
|
||
│ ├── test_different_log_levels.rs
|
||
│ ├── test_init_logging_append_mode.rs
|
||
│ ├── test_init_logging_with_file.rs
|
||
│ ├── test_log_detail_macro.rs
|
||
│ ├── test_log_level_changes.rs
|
||
│ ├── test_log_timed_macro.rs
|
||
│ └── test_simple_logging.rs
|
||
└── test-run Path to test with run.sh
|
||
├── documents Target path PDFs files
|
||
└── originals Source path ODTs files
|
||
</pre>
|
||
|
||
[dir-odt-to-pdf](dir-odt-to-pdf) is the [Cargo.toml](Cargo.toml) <u>pakage name</u> and it should be <u>directory name</u> for path where [just command](https://just.systems/) will be used with [justfile](justfile) commands and recipes .
|
||
|
||
## MacOS APP
|
||
|
||
__DirOdtToPdf.app__ run **run-dir-odt-to-pdf.sh** located in /usr/local/bin
|
||
|
||
**/usr/local/bin/run-dir-odt-to-pdf.sh** can be used as a sequence of several executions of **dir-odt-to-pdf**
|
||
|
||
[justfile](justfile) settings:
|
||
|
||
```bash
|
||
MACOS_APP_PATH := "DirOdtToPdf.app"
|
||
```
|
||
|
||
## Terminal Commands
|
||
|
||
[dir-odt-to-pdf](dir-odt-to-pdf) can be used via commands installed in BIN_APP_PATH(/usr/local/bin):
|
||
|
||
| Command filename | Type | Descripción | Required parameters |
|
||
|------------------|------|--------------|---------------------------------|
|
||
| **dir-odt-to-pdf** | Binary | Executable that converts .odt files to .pdf.<br>Requires source and destination paths | SOURCE (for **.odt** files) DEST (for **.pdf** files) |
|
||
| **run-dir-odt-to-pdf.sh** | Script bash | Script to executes **dir-odt-to-pdf** binary<br>with specific values for **SOURCE** and **DEST**<br>To be used as model. | Does not require (defines them internally) |
|
||
|
||
<small>In MacOS [install.command](macos/install.command) copy above commands to BIN_APP_PATH(/usr/local/bin)</small>
|
||
|
||
## Basic Usage
|
||
```bash
|
||
dir-odt-to-pdf <SOURCE_DIR> <TARGET_DIR> [OPTIONS]
|
||
```
|
||
|
||
### Options
|
||
```
|
||
Required Arguments:
|
||
<SOURCE_DIR> Source directory with .odt, .doc, or .docx files
|
||
<TARGET_DIR> Target directory for PDFs converted files
|
||
|
||
Optional Arguments:
|
||
--log-file <path> Write logs to file instead of console
|
||
--log-level <level> Set log level (error/warn/info/debug/trace)
|
||
Default: info
|
||
--append-log Append to existing log file instead of overwriting
|
||
-h, --help Print help
|
||
-V, --version Print version
|
||
```
|
||
|
||
### Examples
|
||
|
||
1. Basic conversion (logs to console):
|
||
```bash
|
||
dir-odt-to-pdf /path/to/documents /path/to/pdfs
|
||
```
|
||
|
||
2. Log to file:
|
||
```bash
|
||
dir-odt-to-pdf /path/to/documents /path/to/pdfs --log-file conversion.log
|
||
```
|
||
|
||
3. Debug level logging to console:
|
||
```bash
|
||
dir-odt-to-pdf /path/to/documents /path/to/pdfs --log-level debug
|
||
```
|
||
|
||
4. Append to existing log file with custom level:
|
||
```bash
|
||
dir-odt-to-pdf /path/to/documents /path/to/pdfs \
|
||
--log-file conversion.log \
|
||
--log-level debug \
|
||
--append-log
|
||
```
|
||
|
||
### Log Levels
|
||
|
||
Available log levels in increasing verbosity:
|
||
- `error`: Only errors that prevent normal operation
|
||
- `warn`: Warnings about potential issues
|
||
- `info`: General progress information (default)
|
||
- `debug`: Detailed information for troubleshooting
|
||
- `trace`: Very detailed debugging information
|
||
|
||
### Notes
|
||
|
||
- When `--log-file` is specified, output goes only to the file (not to console)
|
||
- Without `--append-log`, the log file is overwritten each time
|
||
- The program will create the target directory if it doesn't exist
|
||
- Existing PDF files are only updated if the source file is newer
|
||
|
||
|
||
### Settings
|
||
|
||
[justfile](justfile) settings:
|
||
|
||
```bash
|
||
APP_PACKAGE := "DirOdtToPdf"
|
||
BIN_APP_PATH := "/usr/local/bin"
|
||
```
|
||
|
||
## Just
|
||
|
||
### Recipes
|
||
|
||
```bash
|
||
Available recipes:
|
||
benchmark # [alias: be]
|
||
build # [alias: b]
|
||
buildall # [aliases: ba, ball]
|
||
clean # [alias: cl]
|
||
doc # [alias: d]
|
||
expand # [alias: e]
|
||
fmt # [alias: f]
|
||
install # [alias: i]
|
||
make-app # [alias: mk, mkapp]
|
||
package # [alias: p, pkg]
|
||
run # [alias: ru]
|
||
runtest # [alias: rt]
|
||
test # [alias: t]
|
||
testcapture # [alias: tc]
|
||
```
|
||
|
||
The following have different **recipes** for **macos** and **linux**
|
||
|
||
- **buildall**
|
||
- **make-run**
|
||
- **make-app**
|
||
- **make-package**
|
||
- **install**
|
||
|
||
### Main Values
|
||
|
||
```bash
|
||
APP_NAME := file_name(justfile_directory())
|
||
APP_PACKAGE := "DirOdtToPdf"
|
||
APP_PACKAGES_PATH := justfile_directory() + "/packages/"
|
||
APP_RESOURCES_PATH := justfile_directory() + "/resources/"
|
||
|
||
MACOS_ROOT_PATH := justfile_directory() + "/macos/"
|
||
MACOS_APP_PATH := "DirOdtToPdf.app"
|
||
MACOS_APP_ICNS_PATH := justfile_directory() + "/resources/icon/app/macos/AppIcon.icns"
|
||
SRC_MACOS := file_name(justfile_directory()) + ".scpt"
|
||
|
||
RUN_SRC := "run.sh"
|
||
BIN_APP_PATH := "/usr/local/bin"
|
||
```
|
||
|
||
## For Development
|
||
|
||
> [!NOTE]
|
||
> [Command-line-options](#options) can be added
|
||
> RUST_LOG environment variable controls env_logger output
|
||
|
||
| Recipe | alias | Descripción | parameters |
|
||
|--------|-------|--------------|--------------------|
|
||
| **build** | b | run cargo | cargo arguments |
|
||
| **buildall** | ba, ball | on MacOS: <br><ul><li>build target releases for aarch64, x86_64</li><li>create universal (apple-darwin)i with <u>lipo</u></li></ul>on Linux: <ul><li>build target release</li></ul> | architecture (arm64 or x86_64 or universal) |
|
||
| **run** | ru | run cargo b -r | cargo arguments |
|
||
| **expand** | e | run cargo expand | cargo arguments |
|
||
| **fmt** | f | run cargo +nightly fmt | cargo arguments |
|
||
| **clean** | cl | run cargo clean | cargo arguments |
|
||
| **doc** | d | run cargo doc --open --no-deps | cargo arguments |
|
||
| **benchmark** | be | run cargo bench | cargo arguments |
|
||
| **test*** | t | run cargo t --features test-sync | cargo arguments |
|
||
| **testcapure*** | tc | run cargo t --features test-sync -- --nocapture | cargo arguments |
|
||
| **runtest** | rt | run [run.sh](run.sh) script using [test](test) directories for **SOURCE** and **DEST** parametets <br> add [Command-line-options](#options) | |
|
||
|
||
---
|
||
|
||
### For tests
|
||
|
||
> [!NOTE]
|
||
> The logger can only be initialized once per process<br>
|
||
> Test by default runs in parallel
|
||
|
||
> [!IMPORTANT]
|
||
> test use **--features test-sync** to run thread safe
|
||
|
||
```rust
|
||
cargo test --features test-sync
|
||
```
|
||
|
||
|
||
Use **--nocapture** to see the output even when tests pass
|
||
|
||
The **RUST_LOG** environment variable controls what gets logged
|
||
|
||
Log files are automatically cleaned up when the **TempDir** is dropped
|
||
|
||
The recommended way to test logging functionality:
|
||
- create a temporary log file
|
||
- write some messages
|
||
- verify their presence in the log
|
||
|
||
|
||
## To work on app
|
||
|
||
| Recipe | alias | Descripción | parameters |
|
||
|--------|-------|--------------|--------------------|
|
||
| **install** | i | on MacOS: <ul><li>install [dir-odt-to-pdf.app](macos/dir-odt-to-pdf.app)</li><li> **make-run** and install commands</li></ul>on Linux: <ul><li>**just make-run**</li><li>install commands</li></ul>| |
|
||
| **make-app** | mk , mkapp | on MacOS: <ul><li>make app [dir-odt-to-pdf.app](macos/dir-odt-to-pdf.app) in [macos](macos) directory</li><li>Add icons and commands</li></ul>on Linux: <ul><li>**just buildall**</li></ul> | architecture (arm64 or x86_64 or universal) |
|
||
| **make-run** | | on MacOS: <ul><li>install [dir-odt-to-pdf.app](macos/dir-odt-to-pdf.app)</li><li>**just delete-run**</li><li>install commands</li></ul>on Linux: <ul><li>**just delete-run**</li><li>install commands</li></ul>| |
|
||
| **delete-run** | | Ask for replace **run-dir-odt-to-pdf.sh** created from [run.sh](run.sh) | |
|
||
| **package** | | on MacOS: <ul><li>**just make-app**</li><li>create **DirOdtToPdf.dmg** DMG package in [packages](packages)<br>with [macos README](macos/README) and [macos install](macos/install.command)</li></ul>on Linux: <ul><li>**just make-app**</li><li>pack binary in compressed archive<br> with [linux](linux) files and commands</li></ul> | architecture (arm64 or x86_64 or universal) |
|