# CIC Shared Pascal Library

A collection of cross-project reusable Pascal units for Lazarus / Free Pascal (FPC).
All units are released under the MIT license.

---

## Unit Catalog

| Unit | Description |
|---|---|
| `uCICExecuteProgram` | Wraps `ShellExecuteEx` to launch external processes and monitor their exit status (Windows / VCL). |
| `uCICHCLzh` | Harpoon Classic LZHUF decoder (LZSS + adaptive Huffman) for LZH bodies in `.RES`/`.RSR` containers; decode only, FPC only. Extracted from HCPE, MIT. |
| `uCICHCResContainer` | Harpoon Classic `.RES` container reader/writer: optional BBFT prefix, offset table, 5- or 7-byte headers (chosen by file name), empty slots, LZH bodies decoded on demand; FPC only. Extracted from HCPE, MIT. Tests: `tests/test_HCRes.pas` with the synthetic vectors in `tests/vectors/lzh`. |
| | **Keep stable:** HCPE (`hcpe.lzh`/`hcpe.container` facades) and HC Launcher depend on `ECICResError`, `ECICLzhError`, `TCICResContainer.FromBytes`/`FromFile`, `CICResReadOffsetTable`, `CICResSlotExtent`, `CICResHeaderSizeForName`, `CICLzhDecode` and the `HCRES_*`/`HCRES1_*` constants. HCPE's Python-generated vectors check behaviour byte for byte. |
| `uCICG4Presenters` | Custom TGlobe4 point-presenter class (`TCICG4PointPresenter`) with extended shape types and heading arrows; Lazarus/LCL port. |
| `uCICMQTTClient` | MQTT 5.0 client (3.1.1 fallback) built on Indy TCP/TLS; no LCL dependency, cross-platform. |
| `uCICOpenSSL3` | Patches FPC's `openssl.pas` at startup to discover OpenSSL 3.x libraries on modern Linux distributions. |
| `uCICOSMTileCommon` | Shared constants and types for OSM slippy-map tile handling (tile size, pixel array types). |
| `uCICOSMTileDecode` | Loads an OSM tile PNG from disk and decodes it to a BGRA pixel array; cross-compiler LCL/VCL workaround included. |
| `uCICOSMTileMath` | Pure functions for converting between latitude/longitude, Mercator Y, and OSM tile indices. |
| `uCICOSMTileStore` | LRU tile cache for decoded OSM tile pixels with file-backed loading from configurable base and download directories. |
| `uCICOSMTileManager` | Coordinator class that owns tile stores and the downloader, eliminating duplicated property-setter code across Globe4/Globe5 consumers. |
| `uCICTileDownloader` | Background HTTP download pipeline for slippy-map tiles; worker thread, atomic write (tmp+rename), main-thread completion callback via `TThread.Queue`. |
| `uCICVersionInformation` | Reads a Windows PE binary's VERSIONINFO resource and returns a `major.minor.release.build` string. |

---

## Usage

### Adding to a Lazarus project

1. Open your project's `.lpi` file in the Lazarus IDE (or edit it directly as XML).
2. Add the path to this directory to the `OtherUnitFiles` compiler option under
   `<CompilerOptions><SearchPaths>`:

   ```xml
   <OtherUnitFiles Value="C:\Prog\Projects\StratsimsOSS\shared\pascal"/>
   ```

3. Add the desired unit names to the `uses` clause of your form or unit.

From the command line (e.g. in a build script):

```
lazbuild --add-package ... MyProject.lpi
```

or pass the search path directly:

```
fpc -Fu"C:\Prog\Projects\StratsimsOSS\shared\pascal" MyProgram.lpr
```

---

## Naming Conventions

- All public units carry the `uCIC` prefix (e.g. `uCICMQTTClient`).
- Units written exclusively for FPC / Lazarus open with:
  ```pascal
  {$mode objfpc}{$H+}
  ```
- Units that must compile under both FPC and Delphi use:
  ```pascal
  {$IFDEF FPC}{$MODE DELPHI}{$ENDIF}
  ```
- `{$WEAKPACKAGEUNIT ON}` is used on units that are safe to include in
  multiple packages without linker conflicts.

---

## Version Control

The library lives in an SVN repository. All changes must be committed to SVN.
Do not add build artefacts (`.dcu`, `.ppu`, `.o`, compiled binaries) to the
repository; they are generated locally.

---

## Testing

A small automated test suite is provided under the `tests/` subdirectory.

```
cd tests
./run_tests.sh
```

See `tests/README.md` for prerequisites, individual test descriptions, and
how to add new tests.