This section is intended to people who want to develop new core features, or to do some maintenance.
The m4/ directory contains the following macros used by configure.ac
and by other NUT macros. Related helpers are grouped below; the source
files contain the individual probes and platform-specific details.
These are build-system interfaces. For the options accepted by the
generated configure script, see
Configure options.
The bundled AX_* macros are described separately below, including NUT
adaptations of macros from the Autoconf Archive.
Defined in m4/nut_arg_with.m4.
--with-FEATURE option. The four-argument form adds
=VALUE_HELP to the help text and requires a non-empty DEFAULT.
Both forms set nut_with_FEATURE and nut_withGiven_FEATURE;
the latter is yes if the option was supplied, including through
--without-FEATURE, and no otherwise. Hyphens in FEATURE become
underscores in these shell variable names.
--enable-FEATURE and
--disable-FEATURE, setting nut_enable_FEATURE and
nut_enableGiven_FEATURE with the same name conversion.
NUT_ARG_EXPAND to expand the default for the help text. The
SINGLEQUOTE variants are intended for paths with escaped dollar
signs and introduce the help value with resolved from.
configure. NAME identifies the temporary shell variable.
This cannot show values which are only determined later, when the
generated configure script runs.
NUT_ARG_WITH. The INVALID_YESNO
variant rejects yes and no, for options expecting flags or paths.
auto), and
an optional display name for the help text. Declare the lower-case
--with-PROJECT-includes, --with-PROJECT-libs or
--with-PROJECT-ldflags option using the INVALID_YESNO helper.
LIBS_AS_LDFLAGS retains the -libs option name but describes its
value as LDFLAGS rather than LIBS.
Take a project name and optional result variable, program names,
default and display name. Declare --with-PROJECT-config and find
the corresponding configuration script. By default the project
name determines the upper-case PROJECT_CONFIG result variable
and lower-case project-config program name. The default is auto;
a disabled script or one that was not found is represented by none.
NUT_ARG_WITH_LIBOPTS_CONFIGSCRIPT_IMPLEM,
NUT_ARG_WITH_LIBOPTS_CONFIGSCRIPT_IMPLEM_2 and
NUT_ARG_WITH_LIBOPTS_CONFIGSCRIPT_IMPLEM_3 are internal helpers which
apply these defaults and perform the search.
The NUT_CHECK_LIB* macros probe headers, libraries and required APIs,
and provide result variables and compiler/linker flags to their callers.
Each guards against repeated checks within one configure run. Many
also cache results for subsequent runs; such a cache assumes unchanged
dependencies and configuration arguments.
The checks for each library evolve organically to compensate for various
bugs in the libraries, pkg-config, etc. or for significant changes between
different generations of those dependencies. The need to keep such code in
manageable sized chunks, as well as to maintain an easily comparable general
code structure (as in diff of these files), and the need to match some
capabilities for others to be based on them, is why we have a separate
macro and source file for each library detection code.
The following table lists the primary result variables and flag prefixes.
For each prefix, the flag variables are PREFIX_CFLAGS and
PREFIX_LIBS, except that libgd uses LIBGD_LDFLAGS for linking.
Result names are not uniformly derived from library or macro names.
| Macro | Result variable(s) | Flag prefix(es) |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The source file names correspond to the lower-case macro names, with
.m4 appended, except NUT_CHECK_LIBGPIO, which is defined in
m4/nut_check_libgpiod.m4 and checks libgpiod. NUT_CHECK_LIBGLIB
checks both GLib and GIO. The SSL checks share the LIBSSL flag variables;
configure.ac selects the backend to use.
Some checks also distinguish library versions or optional APIs. For
example, NUT_CHECK_LIBUSB reads nut_with_usb, including requests
for libusb-1.0 or libusb-0.1 from --with-usb. It reports the selected
variant in nut_usb_lib. NUT_CHECK_LIBMODBUS checks timeout API variants
and the optional USB backend. Consult the corresponding source before
using additional results or changing a dependency check.
m4/nut_check_pkgconfig.m4. Locate and validate
PKG_CONFIG, with --with-pkg-config as an override when a usable
tool has not already been detected. Set have_PKG_CONFIG and
have_PKG_CONFIG_MACROS to report tool and macro availability.
The macro also handles the pkg-config search environment when
cross-compiling.
m4/nut_check_asciidoc.m4. Find the documentation
tools, including ASCIIDOC, A2X, XSLTPROC, XMLLINT, DBLATEX
and SOURCE_HIGHLIGHT. Set nut_have_asciidoc and the
HAVE_ASCIIDOC Automake conditional according to the prerequisites
for man page generation. configure.ac separately tests the ability
to generate the requested documentation formats.
m4/nut_check_aspell.m4. Find ASPELL, check its
version and filtering setup, and test spelling checks. Set
nut_have_aspell, the HAVE_ASPELL Automake conditional and
ASPELL_FILTER_*_PATH variables for the documentation recipes.
m4/nut_check_cppcheck.m4. Find CPPCHECK and check
its version. Set nut_have_cppcheck and the HAVE_CPPCHECK
Automake conditional.
Defined with its helpers in m4/nut_check_python.m4. This is
the entry point used by configure.ac: detect Python interpreters,
reconcile requests and automatic priorities, and determine module
installation paths. Export PYTHON, PYTHON2, PYTHON3 and
PYTHON_DEFAULT through AC_SUBST, with corresponding
HAVE_PYTHON* Automake conditionals. PYTHON_DEFAULT is used for
internal tool calls and script substitutions.
NUT_CHECK_PYTHON, NUT_CHECK_PYTHON2 and NUT_CHECK_PYTHON3 process
the corresponding --with-python* options and validate interpreters.
NUT_CHECK_PYTHON_INTERIM_RESULTS handles missing and required
interpreters; NUT_CHECK_PYTHON_DEFAULT_BEST applies the automatic
priority policy and publishes the interpreter selections.
NUT_CHECK_PYTHON_SITE_PACKAGES, NUT_CHECK_PYTHON2_SITE_PACKAGES and
NUT_CHECK_PYTHON3_SITE_PACKAGES obtain module locations from the
interpreter or the corresponding --with-python*-modules-dir option.
They substitute PYTHON_SITE_PACKAGES, PYTHON2_SITE_PACKAGES and
PYTHON3_SITE_PACKAGES, with matching HAVE_* Automake conditionals.
m4/nut_compiler_family.m4. Identify GCC and Clang compilers
and record version information for CC, CXX and CPP. These
results guide later flag and platform checks.
AX_RUN_OR_LINK_IFELSE. Append the flag to CFLAGS or
CXXFLAGS only where the corresponding checks pass. For -Wno-*
flags, first test the positive -W* spelling to detect unsupported
warnings which a compiler might otherwise silently ignore.
-std= or -ansi.
The second macro repeats that default-standard selection after
other configuration checks.
m4/nut_stash_warnings.m4. Temporarily remove
-W* and -*pedantic* options from CFLAGS, CPPFLAGS and
CXXFLAGS so they do not interfere with configure probes, then
append them back afterwards. These helpers split flags on
whitespace; they do not support embedded spaces in flag values.
m4/nut_check_bool.m4. Probe Boolean types and
values, and define their detected spellings and implementation
properties for include/nut_bool.h.
m4/nut_type_socklen_t.m4. The first checks for
socklen_t, defining a compatible replacement if it is absent or
failing configuration if none can be found. The prerequisite helper
checks socket headers and substitutes HAVE_SYS_SOCKET_H,
HAVE_WINSOCK2_H and HAVE_WS2TCPIP_H as zero-or-one shell values.
SEMLIBS, the nut_have_semaphore_* shell
variables, the HAVE_SEMAPHORE_* preprocessor symbols and the
HAVE_SEMAPHORE_LIBS Automake conditional. Call after the
fcntl.h and sys/stat.h checks, before deciding whether to
enable threading.
m4/nut_check_socketlib.m4. Set and substitute
NETLIBS, adding -lws2_32 when the Windows socket startup probe
succeeds. Also define WINDOWS_SOCKETS on success and declare the
HAVE_WINDOWS_SOCKETS Automake conditional. Other socket library
checks are performed by configure.ac.
m4/nut_func_getnameinfo_argtypes.m4. Determine
compatible argument types for getnameinfo() and define
GETNAMEINFO_TYPE_ARG1, GETNAMEINFO_TYPE_ARG2,
GETNAMEINFO_TYPE_ARG46 and GETNAMEINFO_TYPE_ARG7 when found.
Warn if no matching declaration is found.
m4/nut_check_headers_windows.m4. The header
checks test whether Windows headers can be compiled, with prerequisites
included in the probes. Each defines its HAVE_*_H C symbol on
success and declares the corresponding Automake conditional.
NUT_CHECK_NATIVE_WINDOWS checks for a native Windows target and
declares the DOING_NATIVE_WINDOWS Automake conditional.
m4/nut_check_os.m4. Inspect system identification
files and set OS_NAME and PKG_TARGET when a flavour is found.
NUT_OS_FUNCTIONS provides the shell helpers used for this mapping.
Defined in m4/nut_report_feature.m4.
Report a feature decision immediately and queue it for the final summary.
The FEATURE is a descriptive string such that the scripted sentence
"Checking whether to FEATURE" as well as "FEATURE" itself in the final
list of configuration decisions both make sense (keep in mind casing,
endings, suffixes and verb forms); FLAG is the decision (normally
yes or no); VALUE adds details such as the selected library.
This macro declares the Automake conditional named by VARIABLE, to be
true exactly when FLAG is yes. In that case also define the C symbol
VARIABLE as 1, with DESCRIPTION as its comment.
Some callers pass a sixth argument to customize the check message. The current implementation reads the shell’s sixth positional parameter instead of that M4 argument, so callers cannot rely on this control.
Checking whether to FEATURE.
AC_DEFINE_UNQUOTED, using DESCRIPTION as its comment. These do
not create Automake conditionals. The path variants use separate
summary groups for NUT paths and third-party integration paths;
NUT_REPORT_SETTING_PATH_INTEGRATIONS takes the same four arguments.
Callers must supply appropriate C quoting for string values.
Their configuration progress messages use Checking setting for SETTING.
AC_DEFINE_UNQUOTED; the second only reports it. Neither creates
an Automake conditional.
config.nut_report_feature.log.TAG, adding the group’s title when
first used, except for the driver/program continuation groups.
config.nut_report_feature.log.*.
With --enable-keep_nut_report_feature, it also retains their
combined contents in config.nut_report_feature.log.
AX_C___ATTRIBUTE__
m4/ax_c___attribute__.m4. Check compiler support
for the unused argument/function attributes and the noreturn
attribute. Define the corresponding HAVE___ATTRIBUTE__* symbols.
m4/ax_c_pragmas.m4. The first probes support for
the diagnostic pragmas used by NUT and defines the corresponding
HAVE_PRAGMA_* symbols. The second checks null-string formatting
and compiler warnings, takes --enable-NUT_STRARG-always into
account, and sets the REQUIRE_NUT_STRARG C definition and Automake
conditional. Its cross-compilation fallback only tests linking,
not runtime behaviour.
m4/ax_check_compile_flag.m4. Take a flag, success
action, failure action, extra flags and optional test input. Check
the current language’s compiler, restoring its flags afterwards.
The bundled implementation also recognizes selected compiler
diagnostics about unsupported options.
m4/ax_compare_version.m4. Compare two versions
using an operator, with optional true/false actions. The argument
order is VERSION_A, OP, VERSION_B, ACTION_IF_TRUE,
ACTION_IF_FALSE. Set ax_compare_version to true or false.
See the file’s synopsis for supported operators and precision.
m4/ax_run_or_link_ifelse.m4. Take test source,
success action, failure action, optional C flags and optional C++
flags. Run the test normally, or only link it when cross-compiling.
Temporarily enable fatal warnings and apply the supplied flags,
then restore CFLAGS and CXXFLAGS.
m4/ax_realpath.m4. Resolve a path into VARIABLE,
trying the REALPATH tool if configured, then shell fallback methods.
AX_REALPATH_SHELL_ONELEVEL and AX_REALPATH_SHELL_RECURSIVE
implement those fallback methods. UNITTEST_AX_REALPATH and
UNITTEST_AX_REALPATH_EXPECT are development test helpers in the
same file, rather than normal configuration prerequisites.
m4/ax_realpath_lib.m4. Try to locate a library
file using a GCC/Clang-compatible toolchain and resolve its path
into VARIABLE. FALLBACK is optional and defaults to an empty
value when resolution fails or the compiler is unsupported.
AX_REALPATH_LIB_PREREQ prepares the required platform tools.
Here are some ideas that have come up over the years but haven’t been implemented yet. This may be a good place to start if you’re looking for a rainy day hacking project.
This release is focused on the website and documentation rewrite, using the excellent AsciiDoc.
Some systems don’t want a daemon listening to the network. This can be for security reasons, or perhaps because the system has been squashed down and doesn’t have TCP/IP available. For these situations you could run a driver and program that sits on top of the driver socket to do local monitoring.
This also makes monitoring extremely easy to automate - you don’t need to worry about usernames, passwords or firewalling. Just start a driver and drop this program on top of it.
upsmon currently retains root in a forked process so it can call the shutdown command. The only reason it needs root on most systems is that only privileged users can signal init or send a message on /dev/initctl.
In the case of systems running sysvinit (Slackware, others?), upsmon could just open /dev/initctl while it has root and then drop it completely. When it’s time to shut down, fire a control structure at init across the lingering socket and tell it to enter runlevel 0.
This has been shown to work in local tests, but it’s not portable. It could only be offered as an option for those systems which run that flavor of init. It also needs to be tested to see what happens to the lingering fd over time, such as when init restarts after an upgrade.
For other systems, there is always the possibility of having a suid program which does nothing but prod init into starting a shutdown. Lock down the group access so only upsmon’s unprivileged user can access it, and make that your SHUTDOWNCMD. Then it could drop root completely.
upsmon could run the network monitoring part in a chroot jail if it had a pipe to another process running outside for NOTIFY dispatches. Such a pipe would have to be constructed extremely carefully so an attacker could not compromise it from the jailed process.
A state machine with a tightly defined sequence could do this safely. All it has to do is dispatch the UPS name and event type.
[start] [type] [length] <name> [stop]
Once in awhile, I get requests for a way to shut down based on the UPS temperature, or ambient humidity, or at a certain battery charge level, or any number of things other than an "OB LB" status. It should be obvious that adding a way to monitor all of that in upsmon would bloat upsmon for all those people who really don’t need anything like that.
A separate program that interprets a list of rules and uses it to monitor the UPS equipment is the way to solve this. If you have a condition that needs to be tested, add a rule.
Some of the tools that such a language would need include simple greater-than/less-than testing (if battery.charge < 20), equivalence testing (if ups.model = "SMART-UPS 700"), and some way to set and clear timers.
Due to the expected size and limited audience for such a program, it might have to be distributed separately.
Python may be a good candidate.