halcompile: warn about, and reject colliding, mangled HAL names

[tzuohann]

Problem

A name declared in a .comp file is a C identifier, but it is exported under a mangled HAL identifier: underscores become dashes, and a trailing dash or period is removed. This is documented — docs/src/hal/comp.adoc, HALNAME under Syntax — but nothing says so at the point of use:

pin in float my_input;      ->   component.N.my-input

halcompile compiles that without a word, and halcompile(1) has no naming section, so the author's first sign of it is a HAL file that does not work.

The same mangling has a sharper edge. check_name_ok() (halcompile.g:212) compares only declared names, so two declarations that mangle to one HAL name pass silently. x_y and x_y_ are exactly the two rows of the HALNAME table in comp.adoc that share a HAL identifier:

component collide;
pin in  float x_y;
pin out float x_y_;

$ halcompile --compile collide.comp
Compiling realtime collide.c
Linking collide.so                    # exit 0, no warning

$ halrun -f collide.hal
HAL: ERROR: duplicate variable 'collide.0.x-y'
collide: rtapi_app_main: Invalid argument (-22)
collide.hal:1: insmod for collide failed, returned -1

The failure names neither the .comp file, nor the line, nor the rule that caused it. Reproduced on 2.9.8 as shipped by Debian, and the code is unchanged at 2.9 HEAD (to_hal() at halcompile.g:262).

Change

• check_hal_name() — a HAL-namespace counterpart to check_name_ok(). Two declarations that export the same HAL name are now an error at the offending line, instead of a loadrt failure later.

• A once-per-file warning listing declared names whose HAL identifier differs, e.g.

  my_comp.comp:0: Warning: 3 declared name(s) are exported under a different HAL name:
  my_input -> my-input, my_output -> my-output, my_gain -> my-gain. Use the HAL name in
  HAL files, halcmd and halshow; see HALNAME under 'Syntax' in the Halcompile HAL
  Component Generator documentation, https://linuxcnc.org/docs/html/hal/comp.html
  

  Both messages point at the documentation that describes the mangling.

• -N, --no-name-warnings suppresses that warning. src/hal/components/Submakefile passes it on the two --document rules and the objects/%.c rule, since in-tree HAL names are deliberate, so the build stays as quiet as it is today.

• Docs: a NAMES section in docs/man/man1/halcompile.1; a note under the HALNAME table in comp.adoc.

Component names are left alone — loadrt my_comp keeps its underscores while its pins appear under my-comp.N., which the new NAMES section spells out but does not change.

If 2.9 should stay strictly bugfix-only, the collision check is the bugfix and the warning plus -N can be dropped from this PR on request; they are separable hunks.

Compatibility

The error only fires on a component that cannot load today, so no currently working .comp becomes unbuildable. All 119 in-tree .comp files preprocess with no new error; 64 of them would print the informational warning, which is why the in-tree rules pass -N and a full build gains no new output.

Testing

tests/halcompile/halname/ — two minimal components covering the warning, -N silencing it, and the rejected collision (error text, non-zero exit, no .c produced). tests/halcompile/names still passes unchanged. The man page renders clean through groff -man.

Note

Companion PR for master: #4298. It is the same change adapted to master's layout (halcompile.1.adoc instead of troff, the --adoc rule, type_/dir_ parameter names) — the branches are maintained separately, so neither supersedes the other.

🤖 Generated with Claude Code