Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions docs/src/code/nml-messages.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
44 changes: 43 additions & 1 deletion src/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions tests/build/nml-client-headers/checkresult
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
#!/bin/sh
exit 0 # test failure is indicated by test.sh exit value
37 changes: 37 additions & 0 deletions tests/build/nml-client-headers/client.cc
Original file line number Diff line number Diff line change
@@ -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;
}
3 changes: 3 additions & 0 deletions tests/build/nml-client-headers/skip
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
#!/bin/sh
# Tests the installed header set, so it runs in package builds only.
[ -n "$SYSTEM_BUILD" ]
12 changes: 12 additions & 0 deletions tests/build/nml-client-headers/test.sh
Original file line number Diff line number Diff line change
@@ -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
Loading