Add Gleam language integration to Elixir project

- Rename Gleam module from encoding_simple to encoding
- Move Gleam files from src/aprs/ to src/aprsme/ to match project namespace
- Create custom Mix task for Gleam compilation (lib/mix/tasks/gleam_compile.ex)
- Update EncodingUtils to wrap Gleam implementation instead of pure Elixir
- Add Gleam dependencies to mix.exs and configure build paths
- Update Mix aliases to include Gleam compilation in test and compile tasks
- Add Gleam support to GitHub Actions CI workflow with caching
- Add GLEAM_INTEGRATION.md documentation
- All 357 tests passing with Gleam integration

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-07-18 13:58:21 -05:00

2.7 KiB

Raw Blame History

Gleam Integration Guide

This document describes how Gleam has been integrated into the APRS.me Elixir project.

Setup

Mix Gleam Archive: Installed via mix archive.install hex mix_gleam

Dependencies: Added to mix.exs:

{:gleam_stdlib, ">= 0.60.0 and < 1.0.0", app: false, override: true},
{:gleeunit, "~> 1.0", only: [:dev, :test], runtime: false, app: false}

Project Configuration: Added to mix.exs project config:

archives: [mix_gleam: "~> 0.6"],
erlc_paths: ["build/dev/erlang/aprsme/_gleam_artefacts", "src"],
erlc_include_path: "build/dev/erlang/aprsme/include",

File Structure

/src/ - Gleam source files
/src/aprs/ - APRS-specific Gleam modules
/gleam.toml - Gleam project configuration

Compilation

The project is configured to automatically compile Gleam code when running tests or compiling:

# For development
mix compile.gleam && mix compile

# For tests (automatically compiles Gleam)
mix test

# Manual compilation if needed
mix gleam_compile

The custom gleam_compile task handles:

Running the mix_gleam compiler when available
Falling back to the gleam binary if mix_gleam isn't installed
Copying compiled beam files to the appropriate build directory

Module Naming

Gleam modules are compiled with @ as the separator in BEAM files:

Gleam: aprs/encoding
BEAM: aprs@encoding
Elixir: :aprs@encoding

Current Modules

encoding.gleam

A type-safe implementation of encoding utilities:

sanitize_string/1 - Ensures strings are valid UTF-8, handles Latin-1 conversion
to_float_safe/1 - Safe string to float conversion with Option type
to_hex/1 - Convert binary to hex string representation
has_weather_data/4 - Check if packet contains weather data
encoding_info/1 - Get encoding information about a binary

Elixir Integration

The Aprsme.EncodingUtils module now wraps the Gleam implementation, replacing the original pure Elixir version. The Gleam implementation provides:

Type-safe string sanitization with Latin-1 to UTF-8 conversion
Proper handling of control characters
Safe float conversion with bounds checking
Consistent encoding validation

The migration was completed with all tests passing and no breaking changes to the API.

Testing

The original test suite at /test/aprsme/encoding_utils_test.exs continues to work with the Gleam implementation:

mix test test/aprsme/encoding_utils_test.exs

Future Considerations

Add Gleam compiler to Mix.compilers() once the integration is more stable
Consider migrating more type-critical modules to Gleam
Explore using Gleam's type system for packet validation

2.7 KiB Raw Blame History