Use snprintf(). It’s even provided with a compatibility module if the target system doesn’t have it natively.

If you use snprintf() to load some value into a buffer, make sure you provide the format string. Don’t use user-provided format strings, since that’s an easy way to open yourself up to an exploit.

Don’t use strcat(). We have a neat wrapper for snprintf() called snprintfcat() that allows you to append to char * with a format string and all the usual string length checking of snprintf() routine.

Don’t call syslog() directly. Use upslog_with_errno() and upslogx(). They may write to the syslog, stderr, or both as appropriate. This means you don’t have to worry about whether you’re running in the background or not.

The upslog_with_errno() routine prints your message plus the string expansion of errno. The upslogx() just prints the message.

fatal_with_errno() and fatalx() work the same way, but they also exit(EXIT_FAILURE) afterwards. Don’t call exit() directly.

The upsdebug_with_errno(), upsdebugx(), upsdebug_hex() and upsdebug_ascii() routines use the global nut_debug_level, so you don’t have to mess around with `printf()`s and `if`s yourself. Use them.

xmalloc(), xcalloc(), xrealloc() and xstrdup() all check the results of the base calls before continuing, so you don’t have to. Don’t use the raw calls directly.

The configuration parser, called parseconf, is now up to its fourth major version. It has multiple entry points, and can handle many different jobs. It’s usually used for parsing files, but it can also take input a line at a time or even a character at a time.

You must initialize a context buffer with pconf_init before using any other parseconf function. pconf_encode is the only exception, since it operates on a buffer you supply and is an auxiliary function.

Escaping special characters and quoting multiple-word elements is all handled by the state machine. Using the same code for all config files avoids code duplication.

Drivers may have their own data files, such as lists of hardware, mapping tables, or similar. The difference between a data file and a config file is that users should never be expected to edit a data file under normal circumstances. This technique might be used to add more hardware support to a driver without recompiling.

This is already handled by autoconf, so just include "timehead.h" and you will get the right headers on every system.

This script was originally introduced (following ZeroMQ/ZProject example) to automate CI builds, by automating certain scenarios driven by exported environment variables to set particular configure options and make some targets (chosen by the BUILD_TYPE envvar). It can also be used locally to avoid much typing to re-run those scenarios during development.

Developers can directly use the scripts involved in CI builds to fix existing code on their workstations or to ensure support for new compilers and C standard revisions, e.g. save a local file like this to call the common script with pre-sets:

$ cat _fightwarn-gcc10-gnu17.sh
#!/bin/sh

BUILD_TYPE=default-all-errors \
CFLAGS="-Wall -Wextra -Werror -pedantic -std=gnu17" \
CXXFLAGS="-Wall -Wextra -Werror -std=gnu++17" \
CC=gcc-10 CXX=g++-10 \
        ./ci_build.sh

…and then execute it to prepare a workspace, after which you can go fixing bugs file-by-file running a make after each save to confirm your solutions and uncover the next issue to address :-)

Note that while spelling out sets of warnings can help in a quest to fix certain bugs during development (if only by removing noise from classes of warnings not relevant to the issue one is working on), there is a reasonable set of warnings which NUT codebase actively tries to be clean about (and checks in CI), detailed in the next section.

For the ci_build.sh usage like above, one can instead pass the setting via BUILD_WARNOPT=..., and require that all emitted warnings are fatal for their build, e.g.:

$ cat _fightwarn-clang9-gnu11.sh
#!/bin/sh

BUILD_TYPE=default-all-errors \
BUILD_WARNOPT=hard BUILD_WARNFATAL=yes \
CFLAGS="-std=gnu11" \
CXXFLAGS="-std=gnu++11" \
CC=clang-9 CXX=clang++-9 CPP=clang-cpp \
        ./ci_build.sh

As a rule of thumb, new contributions must not emit any warnings when built in GNU99 mode with a minimal "difficulty" level of warnings. Technically they must survive the part of test matrix across the several platforms tested by NUT CI and marked in project settings as required to pass, to be accepted for a pull request merge.

Developers aiming to post successful pull requests to improve NUT can pass the --enable-warnings option to the configure script in local builds to see how that behaves and ensure that at least in some set-up their contribution is viable. Note that different compiler versions and vendors (gcc/clang/…), building against different OS and third-party dependencies, with different CPU architectures and different language specification revisions, might all complain about different issues — and catching this in as diverse range of set-ups as possible is why we have CI tests.

It can be beneficial for serial developers to set up a local BuildBot, Travis or a Jenkins instance with a matrix test job, to test their local git repository branches with whatever systems they have available.

Since mid-2021, the NUT CI farm is implemented by several virtual servers courteously provided by FossHost. They run various operating systems as build agents, and a Jenkins instance to orchestrate the builds of NUT branches and pull requests on those agents.

This is driven by Jenkinsfile-dynamatrix and a Jenkins Shared Library called jenkins-dynamatrix which prepares a matrix of builds across as many operating systems, bitnesses/architectures, compilers, make programs and C/C++ revisions as it can — based on the population of currently available build agents and capabilities which they expose as agent labels.

This hopefully means that people interested in NUT can contribute to the build farm (and ensure NUT is and remains compatible with their platform) by running a Jenkins Swarm agent with certain labels, which would dial into https://ci.networkupstools.org/ controller. Please contact the NUT maintainer if you want to participate in this manner.

Some further details about the NUT CI farm workers are available in link:config-prereqs.txt and link:ci-farm-lxc-setup.txt documents.

See the .travis.yml file in project sources for a detailed list of third party dependencies and a large matrix of CFLAGS and compiler versions last known to work or to not (yet) work on operating systems available to that CI solution.

+ Local private deployments of Travis CI are possible, so if anybody does use it and has updated markup to share, they are welcome to post PRs.

The NUT project on GitHub has integration with Travis CI to test a large set of compiler and option combinations, covering different versions of gcc and clang, C standards, and requiring to pass builds at least in a mode without warnings (and checking the other cases where any warnings are made fatal).

The options chosen into pre-sets that can be selected by configure script options are ones we use for different layers of CI tests.

Values to note include:

Note that for backwards-compatibility reasons and to help filter out introduction of blatant errors, builds with compilers that claim GCC compatibility can enable a few easy warning presets by default. This can be avoided with an explicit argument to --disable-warnings (or --enable-warnings=no).

Hopefully this mechanism is extensible enough if we would need to add more compilers and/or "difficulty levels" in the future.

Finally, note that such pre-set warnings can be mixed with options passed through CFLAGS or CXXFLAGS values to your local configure run, but it is up to your compiler how it interprets the resulting mix.

Another thing to notice is that the indenting happens with tabs instead of spaces. This lets everyone have their personal tab-width setting without inflicting much pain on other developers. If you use a space, then you’ve fixed the spacing in stone and have really annoyed half of the people out there.

Note that tabs apply only to indenting. Alignment of text after any non-tab character has appeared on the line must be done by spaces in order for it to remain at the same alignment when someone views tabs at a different widths.

One common example for this is multi-line if condition:

        if (something &&
            something_else) {

Another example is tables of definitions that are better aligned with (non-leading) spaces at least between names and values not too many characters wide; it still helps to align the columns with spaces at offsets divisible by 4 or 8 (consistently for the whole table):

#define SHORT_MACRO                         1   /* flag comment */
#define SOMETHING_WITH_A_VERY_LONG_NAME     255 /* flag comment */

If you write something that uses leading spaces, you may get away with it in a driver that’s relatively secluded. However, if we have to work on that code, expect it to get reformatted according to the above.

Patches to existing code that don’t conform to the coding style being used in that file will probably be dropped. If it’s something we really need, it will be grudgingly reformatted before being included.

When in doubt, have a look at Linus’s take on this topic in the Linux kernel — Documentation/CodingStyle. He’s done a far better job of explaining this.

It is better to have lines that are longer than 80 characters than to wrap lines in random places. This makes it easier to work with tools such as "grep", and it also lets each developer choose their own window size and tab setting without being stuck to one particular choice.

Of course, this does not mean that lines should be made unnecessarily long when there is a better alternative (see the note on pretentiousVariableNamingSchemes above). Certainly there should not be more than one statement per line. Please do not use

if (condition) break;

but use the following:

if (condition) {
        break;
}

Whenever a function needs to satisfy a particular API, it can end up taking arguments that are not used in practice (think a too-trivial signal handler). While some compilers offer the facility of decorations like __attribute__(unused), this proved not to be a portable solution. Also the abilities of newer C++ standard revisions are of no help to the vast range of existing systems that run NUT today and expect to be able to do so tomorrow (hence the required C99+ support noted above).

In NUT codebase we prefer to mark un-used variables explicitly in the body of the function (or an #ifdef branch of its code) using the NUT_UNUSED_VARIABLE(varname) as a routine call inside a function body, referring to the macro defined in common.h.

To display in a rough example:

        static void signal_X_handler(int signal_X) {
                NUT_UNUSED_VARIABLE(signal_X);
                /* We have explicitly got nothing to do if we catch signal X */
                return;
        }

We like code that uses const and static liberally. If you don’t need to expose a function or global variable to the outside world, static is your friend. If nobody should edit the contents of some buffer that’s behind a pointer, const keeps them honest.

We always compile with -Wall, so things like const and static help you find implementation flaws. Functions that attempt to modify a constant or access something outside their scope will throw a warning or even fail to compile in some cases. This is what we want.

While C standards allow to write switch statements to "fall through" from handling one case into another, modern compilers frown upon that practice and spew warnings which complicate detecting real bugs in the code (and also looking back at some of the cases written decades ago, it is not trivial to state whether the fall-through was intentional or really is a bug).

Compilers which detect such problem usually offer ways to decorate the code with comments or attributes to keep it quiet it in cases where the jump is intentional; also C++17 introduces special keywords for that in the standard. NUT aiming to be portable and independent of compilers as much as possible, prefers the arguably clearer and standards-based way of using goto into the next intended operation, even though it is a couple of lines away, e.g.:

int uppercase = 0;
switch (char_opt) {
        case 'U':
                uppercase = 1;
                goto fallthrough_case_u_option;
        case 'u':
        fallthrough_case_u_option:
                process_u_option(uppercase);
                break;
}

In trivial cases, like falling through to default which just returns, it may be clearer and more maintainable (adding other option cases in the future) to just return same_result in the code block that would fall through otherwise and avoid goto statements altogether.

If you use a goto that jumps over long distances (see "Switch case fall-through" section above), expect us to drop it when our head stops spinning. It gives us flashbacks to the very old code we wrote. We’ve tried to clean up our act, and you should make the effort as well.

We’re not making a blanket statement about gotos, since everything probably has at least one good use. There are a few cases where a goto is more efficient than any other approach, but you probably won’t encounter them very often in this software.

There are parts of the source tree that do not yet conform to these specs. Part of this is due to the fact that the coding style has been evolving slightly over the course of the project. Some of the code you see in these directories is 5 years old, and things have gotten cleaner since then. Don’t worry — it’ll get cleaned up the next time something in the vicinity gets a visit.

We can’t say enough good things about valgrind. If you do anything with dynamic memory in your code, you need to use this. Just compile with gcc -g and start the program inside valgrind. Run it through the suspected area and then exit cleanly. valgrind will tell you if you’ve done anything dodgy like freeing regions twice, reading uninitialized memory, or if you’ve leaked memory anywhere.

For more information, refer to the Valgrind project.

The summary: please be kind to our eyes. There’s a lot of stuff in here, and many people have put a lot of time and energy to improve it.

Anonymous Git checkouts are possible:

git clone git://github.com/networkupstools/nut.git

or

git clone https://github.com/networkupstools/nut.git

if it is necessary to get around a pesky firewall that blocks the native Git protocol.

For a quicker checkout (when you don’t need the entire repository history), you can limit the depth of the clone:

git clone --depth 1 git://github.com/networkupstools/nut.git

In case the GitHub repository is temporarily unavailable for any reason, we also plan to push to Alioth’s Git server as well. You can add a remote reference to your local repository:

cd path/to/nut
git remote add -f alioth git://anonscm.debian.org/nut/nut.git

There are those who prefer the simplicity and self-consistency of the Mercurial SCM client over the hodgepodge of unique commands which make up Git. Rather than debate the merits of each system, we will gently guide you towards the hg-git project which would theoretically be a transparent bridge between the central Git repository, and your local Mercurial working copy.

Other tools for hg/git interoperability are sure to exist. We would welcome any feedback about this process on the nut-upsdev mailing list.

If you prefer to check out the NUT source code using an SVN client, GitHub has a SVN interface to Git repositories hosted on their servers. You can fork a copy of the NUT repository and commit to your fork with SVN.

Be aware that the examples in the GitHub blog post might result in a checkout that includes all of the current branches, as well as the trunk. You are most likely interested in a command line similar to the following:

svn co https://github.com/networkupstools/nut/trunk nut-trunk-svn