%% erli18n — the runtime library app of the umbrella.
%%
%% This is the app that is published to Hex as the `erli18n` package, built and
%% published from THIS directory (`cd apps/erli18n && rebar3 hex publish
%% package`). Its runtime dependency set, compile options, doc config, and its
%% own publishing `{project_plugins, ...}` live here so the published package is
%% self-contained and does NOT inherit the umbrella's dev/test-only deps
%% (PropEr, etc.). Umbrella-wide dev settings (the quality-gate plugins, the
%% `test` profile, dialyzer/xref/hank policy, and the erlfmt scope) live in the
%% root `rebar.config`.
{erl_opts, [
debug_info,
warnings_as_errors,
warn_unused_vars,
warn_shadow_vars,
warn_obsolete_guard
]}.
%% `telemetry` is declared as a runtime-optional dep:
%% * It is fetched and compiled by `rebar3 deps` so handlers in the
%% consumer can attach.
%% * The lib itself never assumes `telemetry` is loaded — see
%% `erli18n_telemetry.erl` for the `code:ensure_loaded/1` guard
%% pattern that turns every emit into a no-op when the module is
%% missing. See the `erli18n_telemetry` module docs for the rationale.
%%
%% Naming/version policy: telemetry 1.x is the stable line maintained by
%% the BEAM Telemetry WG (https://github.com/beam-telemetry/telemetry).
%% Version constraint is intentionally loose to interoperate with the
%% consumer's existing dep tree (Phoenix, Ecto, Oban, etc. all pull 1.x).
{deps, [
{telemetry, "~> 1.3"}
]}.
%% Per-app Hex/doc publishing plugins, scoped to THIS app. The `erli18n` package
%% is published from inside this directory (`cd apps/erli18n && rebar3 hex
%% publish ...` — see `.github/workflows/release.yml`), so the `hex`/`ex_doc`
%% providers must be on THIS app's plugin path; a per-app `rebar3 hex` run with
%% no per-app plugins aborts with `Command hex not found`. Publishing each app
%% from its own directory (rather than `--app NAME` from the umbrella root) is
%% the uniform, self-contained model both packages use — and is REQUIRED for the
%% plugin so its sibling `erli18n` dep lands in the published `requirements` (see
%% the rationale in `apps/rebar3_erli18n/rebar.config`). erli18n's only dep
%% (`telemetry`) is a published Hex package, so its per-app build resolves a
%% level-0 `{pkg, telemetry, ...}` lock and publishes `requirements =
%% {telemetry, "~> 1.3"}` correctly either way; we keep the per-app path here for
%% symmetry with the plugin and to match the exemplar's self-contained app model
%% (open-telemetry/opentelemetry-erlang publishes each app from its own dir).
{project_plugins, [
{rebar3_hex, "~> 7.0"},
{rebar3_ex_doc, "~> 0.2"}
]}.
{shell, [{apps, [erli18n]}]}.
%% ExDoc config (extras + main page + source URL) for the erli18n package.
%% This block is the single source of truth for the package's doc options;
%% `scripts/gen_docs.sh` reads it (via scripts/ex_doc_config.escript) and
%% renders the HTML site straight from the native `-doc`/`-moduledoc` BEAM
%% chunks (EEP-48) using the ex_doc escript. It lives in the app (not the
%% umbrella root) so the published `erli18n` package owns its own doc config.
%%
%% The `{extras, ...}` list references ONLY this app's own files (README,
%% CHANGELOG, LICENSE) — all three now ship inside the package tarball
%% (they are matched by ?DEFAULT_FILES relative to the app dir; see
%% rebar3_hex_build.erl:118-133 and rebar3_hex_file.erl:11-13 in
%% rebar3_hex v7.1.0). The repo-root community docs (CONTRIBUTING,
%% CODE_OF_CONDUCT, SECURITY) are intentionally omitted: they are
%% umbrella-level dev docs, not part of the erli18n package.
%%
%% NOTE: `rebar3 ex_doc` is currently unusable for this project. The plugin
%% always runs EDoc to generate chunks first, and EDoc's legacy wiki parser
%% throws on a Markdown backtick in an ordinary `%%` comment — an upstream
%% bug. `scripts/gen_docs.sh` skips that vestigial EDoc step (ex_doc reads
%% the docs from the BEAM, not from EDoc's chunks). `rebar3 hex publish docs`
%% is affected by the same upstream bug.
%% `extras` ordering is the sidebar ordering. The README is the landing page
%% (`{main, "readme"}`); the three narrative guides under `guides/` are short
%% prose on-ramps lifted from the README sections (install/lookup, CLDR
%% pluralization, locale negotiation + the Cowboy/Elli middleware) so HexDocs
%% ships guides, not only an API reference. They are app-relative paths: the
%% same bare form as README/CHANGELOG/LICENSE, resolved against `apps/erli18n/`
%% by gen_docs.sh's <extras-base> (and directly when ex_doc runs from the app
%% dir). The guides are doc-build inputs rendered to HTML and published via
%% `rebar3 hex publish docs --doc-dir doc`; they are NOT part of the source
%% tarball's `files` whitelist (neither is `scripts/`).
%%
%% `groups_for_modules` / `groups_for_extras` give the 14-module package a
%% navigable sidebar instead of one flat alphabetical list. Module groups use
%% bare atoms (ex_doc matches an atom against the module name exactly); extra
%% groups use bare app-relative paths (ex_doc matches a binary against the
%% extra's input path exactly), and `scripts/ex_doc_config.escript` joins the
%% <extras-base> onto the extra-group patterns exactly as it does for `extras`.
%% Every module is placed in exactly one group so none fall back to an
%% unlabeled list. See the ex_doc config keys at
%% https://hexdocs.pm/ex_doc/Mix.Tasks.Docs.html and the matching logic in
%% ExDoc.Config (match_module/4, match_extra/2).
{ex_doc, [
{extras, [
"README.md",
"guides/getting-started.md",
"guides/pluralization.md",
"guides/locale-negotiation.md",
"CHANGELOG.md",
"LICENSE"
]},
{main, "readme"},
{source_url, "https://github.com/eagle-head/erli18n"},
{groups_for_extras, [
{"Guides", [
"guides/getting-started.md",
"guides/pluralization.md",
"guides/locale-negotiation.md"
]},
{"About", [
"CHANGELOG.md",
"LICENSE"
]}
]},
{groups_for_modules, [
{"Facade", [erli18n]},
{"Catalogs & loading", [erli18n_server, erli18n_pt_store]},
{"PO format", [erli18n_po]},
{"Pluralization", [erli18n_plural]},
{"Interpolation", [erli18n_interp]},
{"Locale negotiation", [erli18n_negotiate]},
{"HTTP middleware", [
erli18n_http,
erli18n_http_apply,
erli18n_cowboy,
erli18n_elli
]},
{"Telemetry", [erli18n_telemetry]},
{"Application", [erli18n_app, erli18n_sup]}
]},
{prefix_ref_vsn_with_v, false}
]}.
%% Hex packaging. Wire the doc provider to ExDoc so that
%% `rebar3 hex publish docs` renders the site via `rebar3_ex_doc`.
{hex, [{doc, #{provider => ex_doc}}]}.