Skip to content

Commit 73b22f8

Browse files
hansuhansu
committed
docs: improve "HAL Component Generator" doc page (halcompile)
1 parent 538271c commit 73b22f8

1 file changed

Lines changed: 85 additions & 82 deletions

File tree

‎docs/src/hal/comp.adoc‎

Lines changed: 85 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,82 @@ sudo apt install linuxcnc-uspace-dev
5454

5555
Another method is using the Synaptic package manager, from the Applications menu, to install the `linuxcnc-dev` or `linuxcnc-uspace-dev` packages.
5656

57+
58+
== Compiling
59+
60+
=== Inside the source tree
61+
62+
Place the `.comp` file in the source directory `linuxcnc/src/hal/components` and re-run `make`.
63+
'Comp' files are automatically detected by the build system.
64+
65+
If a `.comp` file is a driver for hardware, it may be placed in `linuxcnc/src/hal/drivers`
66+
and will be built unless LinuxCNC is configured as a non-realtime simulator.
67+
68+
=== Realtime components outside the source tree
69+
70+
'halcompile' can process, compile, and install a realtime component in a single step,
71+
placing `rtexample.ko` in the LinuxCNC realtime module directory:
72+
73+
----
74+
[sudo] halcompile --install rtexample.comp
75+
----
76+
77+
[NOTE]
78+
sudo (for root permission) is needed when using LinuxCNC from a deb package install.
79+
When using a Run-In-Place (RIP) build, root privileges should not be needed.
80+
81+
Or, it can process and compile in one step, leaving `example.ko` (or `example.so` for the simulator) in the current directory:
82+
83+
----
84+
halcompile --compile rtexample.comp
85+
----
86+
87+
Or it can simply process, leaving `example.c` in the current directory:
88+
89+
----
90+
halcompile rtexample.comp
91+
----
92+
93+
'halcompile' can also compile and install a component written in C, using the `--install` and `--compile` options shown above:
94+
95+
----
96+
[sudo] halcompile --install rtexample2.c
97+
----
98+
99+
man-format documentation can also be created from the information in the declaration section:
100+
101+
----
102+
halcompile --document -o example.9 rtexample.comp
103+
----
104+
105+
The resulting manpage, 'example.9' can be viewed with
106+
107+
----
108+
man ./example.9
109+
----
110+
111+
or copied to a standard location for manual pages.
112+
113+
=== Non-realtime components outside the source tree
114+
115+
'halcompile' can process, compile, install, and document non-realtime components:
116+
117+
----
118+
halcompile non-rt-example.comp
119+
halcompile --compile non-rt-example.comp
120+
[sudo] halcompile --install non-rt-example.comp
121+
halcompile --document non-rt-example.comp
122+
----
123+
124+
For some libraries (for example modbus) it might be necessary to add extra compiler and linker arguments to enable the compiler to find and link the libraries.
125+
In the case of .comp files this can be done via "option" statements in the `.comp` file.
126+
For `.c` files this is not possible so the `--extra-compile-args` and `--extra-link-args` parameters can be used instead.
127+
As an example, this command line can be used to compile the `vfdb_vfd.c` component out-of-tree.
128+
----
129+
halcompile --userspace --install --extra-compile-args="-I/usr/include/modbus" --extra-link-args="-lm -lmodbus -llinuxcncini" vfdb_vfd.c
130+
----
131+
NOTE: The effect of using both command-line and in-file extra-args is undefined.
132+
57133
== Using a Component
58134

59135
Components need to be loaded and added to a thread before it can be employed.
@@ -67,21 +143,21 @@ loadrt ddt
67143
addf ddt.0 servo-thread
68144
----
69145

70-
More information on 'loadrt' and 'addf' can be found in the
146+
More information on `loadrt` and `addf` can be found in the
71147
<<cha:basic-hal-reference,HAL Basics>>.
72148

73149
To test your component you can follow the examples in the <<cha:hal-tutorial,HAL Tutorial>>.
74150

75151
== Definitions
76152

77-
* 'component' - A component is a single real-time module, which is loaded with 'halcmd loadrt'.
78-
One '.comp' file specifies one component. The component name and file name must match.
153+
* *component* - A component is a single real-time module, which is loaded with `Halcmd loadrt`.
154+
One `.comp` file specifies one component. The component name and file name must match.
79155

80-
* 'instance' - A component can have zero or more instances.
156+
* *instance* - A component can have zero or more instances.
81157
Each instance of a component is created equal (they all have the same pins, parameters,
82158
functions, and data) but behave independently when their pins, parameters, and data have different values.
83159

84-
* 'singleton' - It is possible for a component to be a "singleton", in which case exactly one instance is created.
160+
* *singleton* - It is possible for a component to be a "singleton", in which case exactly one instance is created.
85161
It seldom makes sense to write a 'singleton' component, unless there can literally only be a single object of that kind in the system
86162
(for instance, a component whose purpose is to provide a pin with the current UNIX time, or a hardware driver for the internal PC speaker).
87163

@@ -101,7 +177,7 @@ This can be useful in components that need the timing information.
101177

102178
== Syntax
103179

104-
A '.comp' file consists of a number of declarations, followed by ';;' on a line of its own, followed by C code implementing the module's functions.
180+
A `.comp` file consists of a number of declarations, followed by `;;` on a line of its own, followed by C code implementing the module's functions.
105181

106182
Declarations include:
107183

@@ -381,8 +457,8 @@ When the item is a conditional item, it is only legal to refer to it when its 'c
381457

382458
== Components with one function
383459

384-
If a component has only one function and the string "FUNCTION" does not appear anywhere after ';;',
385-
then the portion after ';;' is all taken to be the body of the component's single function.
460+
If a component has only one function and the string `"FUNCTION"` does not appear anywhere after `;;`,
461+
then the portion after `;;` is all taken to be the body of the component's single function.
386462
See the <<code:simple-comp-example,Simple Comp>> for an example of this.
387463

388464
== Component Personality
@@ -417,79 +493,6 @@ If the requested number of instances exceeds the number of allowed personalities
417493
personalities are assigned by indexing modulo the number of allowed personalities.
418494
A message is printed denoting such assignments.
419495

420-
== Compiling
421-
422-
Place the '.comp' file in the source directory 'linuxcnc/src/hal/components' and re-run 'make'.
423-
'Comp' files are automatically detected by the build system.
424-
425-
If a '.comp' file is a driver for hardware, it may be placed in 'linuxcnc/src/hal/drivers'
426-
and will be built unless LinuxCNC is configured as a non-realtime simulator.
427-
428-
== Compiling realtime components outside the source tree
429-
430-
'halcompile' can process, compile, and install a realtime component in a single step,
431-
placing 'rtexample.ko' in the LinuxCNC realtime module directory:
432-
433-
----
434-
[sudo] halcompile --install rtexample.comp
435-
----
436-
437-
[NOTE]
438-
sudo (for root permission) is needed when using LinuxCNC from a deb package install.
439-
When using a Run-In-Place (RIP) build, root privileges should not be needed.
440-
441-
Or, it can process and compile in one step, leaving 'example.ko' (or 'example.so' for the simulator) in the current directory:
442-
443-
----
444-
halcompile --compile rtexample.comp
445-
----
446-
447-
Or it can simply process, leaving 'example.c' in the current directory:
448-
449-
----
450-
halcompile rtexample.comp
451-
----
452-
453-
'halcompile' can also compile and install a component written in C, using the '--install' and '--compile' options shown above:
454-
455-
----
456-
[sudo] halcompile --install rtexample2.c
457-
----
458-
459-
man-format documentation can also be created from the information in the declaration section:
460-
461-
----
462-
halcompile --document rtexample.comp
463-
----
464-
465-
The resulting manpage, 'example.9' can be viewed with
466-
467-
----
468-
man ./example.9
469-
----
470-
471-
or copied to a standard location for manual pages.
472-
473-
== Compiling non-realtime components outside the source tree
474-
475-
'halcompile' can process, compile, install, and document non-realtime components:
476-
477-
----
478-
halcompile non-rt-example.comp
479-
halcompile --compile non-rt-example.comp
480-
[sudo] halcompile --install non-rt-example.comp
481-
halcompile --document non-rt-example.comp
482-
----
483-
484-
For some libraries (for example modbus) it might be necessary to add extra compiler and linker arguments to enable the compiler to find and link the libraries.
485-
In the case of .comp files this can be done via "option" statements in the .comp file.
486-
For .c files this is not possible so the --extra-compile-args and --extra-link-args parameters can be used instead.
487-
As an example, this command line can be used to compile the vfdb_vfd.c component out-of-tree.
488-
----
489-
halcompile --userspace --install --extra-compile-args="-I/usr/include/modbus" --extra-link-args="-lm -lmodbus -llinuxcncini" vfdb_vfd.c
490-
----
491-
NOTE: The effect of using both command-line and in-file extra-args is undefined.
492-
493496
== Examples
494497

495498
=== constant
@@ -639,7 +642,7 @@ void user_mainloop(void) {
639642
}
640643
----
641644

642-
=== logic
645+
=== logic (using personality)
643646

644647
This realtime component shows how to use "personality" to create variable-size arrays and optional pins.
645648

0 commit comments

Comments
 (0)