diff --git a/docs/src/code/nml-messages.adoc b/docs/src/code/nml-messages.adoc index 307066ea39d..219b3bda86f 100644 --- a/docs/src/code/nml-messages.adoc +++ b/docs/src/code/nml-messages.adoc @@ -7,6 +7,33 @@ List of NML messages. + For details see `src/emc/nml_intf/emc.hh`. +[[sec:nml-msg:client]] +== Writing a client outside the tree + +The emc headers a client compiles against are installed into +`$(includedir)/linuxcnc` (`/usr/include/linuxcnc` in a packaged build); the +libnml ones keep their directory under it, because that is how they include +each other. One include path is enough: + +[source,c] +---- +#include "emc_nml.hh" +#include "libnml/nml/nml.hh" +---- + +and links the same libraries the Python module uses: + +[source,sh] +---- +c++ -I/usr/include/linuxcnc client.cc -llinuxcnc -lnml -llinuxcncini +---- + +The exported set is the `NML_HEADERS`, `NML_HEADERS_NML`, `NML_HEADERS_CMS` +and `NML_HEADERS_RCS` lists in `src/Makefile`. It is +exported for as long as NML exists and is not a compatibility promise for the +NML replacement: when NML is removed these headers go with it, and clients +move to the interface the replacement publishes. + [[sec:nml-msg:operator]] == OPERATOR diff --git a/src/Makefile b/src/Makefile index 05715dd7985..7656e568230 100644 --- a/src/Makefile +++ b/src/Makefile @@ -387,6 +387,42 @@ build-software: $(INFILES) # where they are used from, not copies, which is why no rule builds them. HEADERS := $(wildcard ../include/*.h ../include/*.hh) +# The NML client headers. The emc ones are installed flat, next to the +# headers above; the libnml ones keep their directory, because their includes +# are written as "libnml/nml/nml_type.hh" and a client only adds +# $(includedir)/linuxcnc to its include path. +# +# This set exists for as long as NML does. It is not an interface the NML +# replacement has to emulate: when NML goes, these headers go with it. +NML_HEADERS := \ + emc/rcs_status.hh \ + emc/nml_intf/canon.hh \ + emc/nml_intf/canon_position.hh \ + emc/nml_intf/debugflags.h \ + emc/nml_intf/emccfg.h \ + emc/nml_intf/emcglb.h \ + emc/nml_intf/emc.hh \ + emc/nml_intf/emc_nml.hh \ + emc/nml_intf/emctool.h \ + emc/nml_intf/interp_codes.h \ + emc/nml_intf/modal_state.hh \ + emc/nml_intf/state_tag.h + +NML_HEADERS_NML := \ + libnml/nml/cmd_msg.hh \ + libnml/nml/nml.hh \ + libnml/nml/nmlmsg.hh \ + libnml/nml/nml_oi.hh \ + libnml/nml/nml_type.hh \ + libnml/nml/stat_msg.hh + +NML_HEADERS_CMS := \ + libnml/cms/cms.hh \ + libnml/cms/cms_user.hh + +NML_HEADERS_RCS := \ + libnml/rcs/rcs.hh + # Add converting of %.po files TARGETS += $(patsubst po/%.po, ../share/locale/%/LC_MESSAGES/linuxcnc.mo, $(wildcard po/*.po)) TARGETS += $(patsubst po/gmoccapy/%.po, ../share/locale/%/LC_MESSAGES/gmoccapy.mo, $(wildcard po/gmoccapy/*.po)) @@ -677,7 +713,13 @@ endif cp --no-dereference $(wildcard ../lib/*.so) $(DESTDIR)$(libdir) -ldconfig $(DESTDIR)$(libdir) $(FILE) ../lib/linuxcnc/canterp.so $(DESTDIR)$(libdir)/linuxcnc/ - $(FILE) $(HEADERS) $(DESTDIR)$(includedir)/linuxcnc/ + $(FILE) $(HEADERS) $(NML_HEADERS) $(DESTDIR)$(includedir)/linuxcnc/ + $(DIR) $(DESTDIR)$(includedir)/linuxcnc/libnml/nml \ + $(DESTDIR)$(includedir)/linuxcnc/libnml/cms \ + $(DESTDIR)$(includedir)/linuxcnc/libnml/rcs + $(FILE) $(NML_HEADERS_NML) $(DESTDIR)$(includedir)/linuxcnc/libnml/nml/ + $(FILE) $(NML_HEADERS_CMS) $(DESTDIR)$(includedir)/linuxcnc/libnml/cms/ + $(FILE) $(NML_HEADERS_RCS) $(DESTDIR)$(includedir)/linuxcnc/libnml/rcs/ $(TREE) $(NC_FILES) $(DESTDIR)$(ncfilesdir) $(EXE) ../nc_files/M101 $(DESTDIR)$(ncfilesdir) $(FILE) Makefile.modinc $(DESTDIR)$(datadir)/linuxcnc diff --git a/tests/build/nml-client-headers/checkresult b/tests/build/nml-client-headers/checkresult new file mode 100755 index 00000000000..24dc9aa53e3 --- /dev/null +++ b/tests/build/nml-client-headers/checkresult @@ -0,0 +1,2 @@ +#!/bin/sh +exit 0 # test failure is indicated by test.sh exit value diff --git a/tests/build/nml-client-headers/client.cc b/tests/build/nml-client-headers/client.cc new file mode 100644 index 00000000000..6a1a636ae52 --- /dev/null +++ b/tests/build/nml-client-headers/client.cc @@ -0,0 +1,37 @@ +/* Copyright (c) 2026 All rights reserved. + * License: GPL Version 2 + * + * Compiles and links against the installed headers only, the way an + * out-of-tree NML client does: one include path, no source tree, no + * generated files. + */ +#include "emc.hh" +#include "emc_nml.hh" +#include "emccfg.h" +#include "emcglb.h" +#include "state_tag.h" + +/* The libnml headers keep their directory under $(includedir)/linuxcnc, + because that is how they include each other. */ +#include "libnml/nml/nml.hh" +#include "libnml/nml/nml_oi.hh" + +int main() +{ + EMC_STAT status; + EMC_TASK_SET_MODE set_mode; + EMC_TRAJ_STAT traj; + + set_mode.mode = EMC_TASK_MODE::MANUAL; + traj.mode = EMC_TRAJ_MODE::COORD; + (void)status; + (void)set_mode; + (void)traj; + + /* Addresses only: the link has to find the two format functions in + liblinuxcnc and libnml, which is what proves the libraries that go + with these headers are installed too. */ + int (*emc_format)(NMLTYPE, void *, CMS *) = &emcFormat; + int (*nml_error_format)(NMLTYPE, void *, CMS *) = &nmlErrorFormat; + return emc_format == nullptr || nml_error_format == nullptr; +} diff --git a/tests/build/nml-client-headers/skip b/tests/build/nml-client-headers/skip new file mode 100755 index 00000000000..1929fa7d3b2 --- /dev/null +++ b/tests/build/nml-client-headers/skip @@ -0,0 +1,3 @@ +#!/bin/sh +# Tests the installed header set, so it runs in package builds only. +[ -n "$SYSTEM_BUILD" ] diff --git a/tests/build/nml-client-headers/test.sh b/tests/build/nml-client-headers/test.sh new file mode 100755 index 00000000000..90e1fe84115 --- /dev/null +++ b/tests/build/nml-client-headers/test.sh @@ -0,0 +1,12 @@ +#!/bin/bash +# The NML client headers are installed flat, together with the libraries they +# need. Compile and link a client against the installed set only; that is the +# build an out-of-tree UI of this kind has to be able to do. +set -e + +g++ -std=c++17 -Wall -Wextra -Werror -I"${HEADERS}" -c client.cc -o client.o +g++ -o client client.o -L"${LIBDIR}" -Wl,-rpath,"${LIBDIR}" \ + -llinuxcnc -lnml -llinuxcncini + +rm -f client client.o +exit 0