Rebar3 Diameter Compiler Plugin

Authors: Carlos Eduardo de Paula.

Rebar3 Diameter Compiler Plugin

A rebar3 plugin for compiling Diameter protocol dictionary files (.dia) in Erlang projects. This plugin automatically discovers, resolves dependencies, and compiles .dia files to generate the corresponding .erl and .hrl files needed for Diameter applications.

Features

Automatic Discovery: Finds all .dia files in your project's dia/ directory
Dependency Resolution: Analyzes @inherits directives and compiles files in correct order
Configurable Output: Customizable source and include output directories
Integration: Seamlessly integrates with rebar3 build process via provider hooks
Cleanup: Provides clean command to remove generated files
Cross-Platform: Works across different OTP versions (24-28+)

Installation

From Hex.pm (Recommended)

Add the plugin to your rebar.config:

{plugins, [
    rebar3_diameter_compiler
]}.

{provider_hooks, [
    {pre, [
        {compile, {diameter, compile}},
        {clean, {diameter, clean}}
    ]}
]}.

From GitHub

For development or latest features:

{plugins, [
    {rebar3_diameter_compiler, {git, "https://github.com/carlosedp/rebar3_diameter_compiler.git", {branch, "master"}}}
]}.

{provider_hooks, [
    {pre, [
        {compile, {diameter, compile}},
        {clean, {diameter, clean}}
    ]}
]}.

Usage

Basic Usage

Once configured with provider hooks, the plugin runs automatically:

$ rebar3 compile
===> Compiling diameter files...
===> Compiling diameter_3gpp_base.dia
===> Compiling myapp.dia

Manual Commands

You can also run the plugin commands directly:

# Compile diameter files
$ rebar3 diameter compile

# Clean generated files
$ rebar3 diameter clean

Configuration

The plugin supports several configuration options in your rebar.config:

Diameter Options (dia_opts)

{dia_opts, [
    {outdir, "custom_src"},           % Output directory for .erl files (default: "src")
    {include, ["deps/diameter_base"]}, % Additional include paths
    {recursive, true}                 % Recursively search for .dia files (default: true)
]}.

Compilation Order (dia_first_files)

Specify files that should be compiled first, useful for base dictionaries:

{dia_first_files, [
    "diameter_base.dia",
    "diameter_3gpp_base.dia"
]}.

Selective Compilation (dia_only_files)

Compile only specific dictionaries instead of all discovered .dia files:

{dia_only_files, [
    "diameter_3gpp_base",    % Dictionary names (without .dia extension)
    "my_custom_dictionary"
]}.

Project Structure

The plugin expects and generates files in the following structure:

myapp/
├── dia/                    % Source .dia files
│   ├── diameter_base.dia
│   ├── my_dictionary.dia
│   └── custom_app.dia
├── src/                    % Generated .erl files (configurable)
│   ├── diameter_base.erl
│   ├── my_dictionary.erl
│   └── custom_app.erl
├── include/                % Generated .hrl files
│   ├── diameter_base.hrl
│   ├── my_dictionary.hrl
│   └── custom_app.hrl
└── rebar.config

Dependency Management

The plugin automatically handles dependencies declared with @inherits directives in .dia files:

;; In my_dictionary.dia
@name my_dictionary
@inherits diameter_base

;; This will ensure diameter_base is compiled before my_dictionary

The dependency resolver:

Parses all .dia files to extract @inherits directives
Builds a dependency graph
Performs topological sort to determine compilation order
Detects circular dependencies and reports errors

Generated Files

For each .dia file, the plugin generates:

.erl file: Erlang module with diameter codec functions
.hrl file: Header file with record definitions and constants
.beam file: Compiled bytecode (automatically loaded)

Examples

Basic Diameter Dictionary

;; File: dia/my_app.dia
@name my_app
@vendor 12345 "My Company"

@avp_types
My-AVP 1000 Unsigned32 M

@messages
My-Request ::= < Diameter Header: 1001, REQ, PXY >
              { My-AVP }

My-Answer ::= < Diameter Header: 1001, PXY >
             { Result-Code }
             [ My-AVP ]

Dictionary with Inheritance

;; File: dia/my_extension.dia
@name my_extension
@inherits my_app

@avp_types
Extension-AVP 2000 UTF8String M

@messages
Extended-Request ::= < Diameter Header: 2001, REQ, PXY >
                    { My-AVP }
                    { Extension-AVP }

Integration with Diameter Application

Once compiled, use the generated modules in your Diameter application:

%% Start diameter service with compiled dictionary
diameter:start_service(my_service, [
    {application, [{dictionary, my_app},
                   {module, my_app_callback}]}
]).

Troubleshooting

Common Issues

Compilation Errors: Check .dia file syntax and ensure all @inherits dependencies are available
Missing Dependencies: Verify that inherited dictionaries are present in the dia/ directory
Generated Files Not Found: Check dia_opts outdir configuration and ensure directories exist
Circular Dependencies: Review @inherits directives to eliminate circular references

Debug Mode

Enable verbose logging to see detailed compilation information:

$ DEBUG=1 rebar3 diameter compile

Contributing

Contributions are welcome! Please see the GitHub repository for:

Bug reports and feature requests
Pull requests
Documentation improvements

Repository: https://github.com/carlosedp/rebar3_diameter_compiler

Generated by EDoc