dir-odt-to-pdf/README.md

# 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 <br> (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) |