The device drivers use main.c as their core.

To write a new driver, you create a file with a series of support functions that will be called by main. These all have names that start with upsdrv_, and they will be called at different times by main depending on what needs to happen.

See the driver documentation for information on writing drivers, and also refer to the skeletal driver in skel.c.

Avoid things that will break on other systems. All the world is not an x86 Linux box.

/* Comments look like this. */
// Not like this.

function do_stuff(void)
{
        check_something();

        int a;

        a = do_something_else();
}

function do_stuff(void)
{
        /* This should declare "int i;" first, then use it in "for" loop: */
        for (int i = 0; i < INT_MAX; ++i) { ... }

        /* Additional loops cause also an error about re-declaring a variable: */
        for (int i = 10; i < 15; ++i) { ... }
}

To ease and automate the build scenarios which were deemed important for quality assurance and non-regression checks of NUT, several solutions were introduced over time.

$ 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

$ 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

BUILD_TYPE=fightwarn-clang ./ci_build.sh

SHELL=/bin/bash CONFIG_SHELL=/bin/bash CI_SHELL_IS_FLAKY=true \
./ci_build.sh

22:26:01  FINISHED with exit-code 2 cmd:  (
22:26:01  [ -x ./ci_build.sh ] || exit
22:26:01
22:26:01  eval BUILD_TYPE="default-alldrv" BUILD_WARNOPT="hard" \
    BUILD_WARNFATAL="yes" MAKE="make"  CC=gcc-10 CXX=g++-10 \
    CPP=cpp-10 CFLAGS='-std=gnu99 -m64' CXXFLAGS='-std=gnu++11 -m64' \
    LDFLAGS='-m64' ./ci_build.sh
22:26:01  )

22:28:18  FINISHED with exit-code 0 cmd:  ( [ -x configure ] || exit; \
    eval  CC=clang-9 CXX=clang++-9 CPP=clang-cpp-9 CFLAGS='-std=c11 -m64' \
    CXXFLAGS='-std=c++11 -m64' LDFLAGS='-m64' time ./configure )

Much of NUT has been coded using classic editors of developers' preference, like vi, nano, Midnight Commander mcedit, gedit/pluma, NotePad++ and tools like meld or WinMerge for file comparison and merge.

Modern IDEs however do offer benefits, specifically for live debugging sessions in a more convenient fashion than with command-line gdb directly. They also simplify writing AsciiDoc files with real-time rendering support.

IDEs that were tested to work with NUT development and real-time debugger tracing include:

Some supporting maintenance and development is doable with IntelliJ IDEA, making some things easier to do than with a simple Notepad, but it does not handle C/C++ development as such.

:; cp ./clients/.libs/libupsclient-6.dll ./drivers/.libs/

CFLAGS="$CFLAGS -g3 -gdwarf-2"
CXXFLAGS="$CXXFLAGS -g3 -gdwarf-2"

This is how we do things:

int open_subspace(char *ship, int privacy)
{
        if (!privacy)
                return insecure_channel(ship);

        if (!init_privacy(ship))
                fatal_with_errno("Can't open secure channel");

        return secure_channel(ship);
}

The basic idea is that we try to group things into functions, and then find ways to drop out of them when we can’t go any further. There’s another way to program this involving a big else chunk and a bunch of braces, and it can be hard to follow. You can read this from top to bottom and have a pretty good idea of what’s going on without having to track too much { } nesting and indenting.

We don’t really care for pretentiousVariableNamingSchemes, but you can probably get away with it in your own driver that we will never have to touch. If your function or variable names start pushing important code off the right margin of the screen, expect them to meet the byte chainsaw sooner or later.

All types defined with typedef should end in _t, because this is easier to read, and it enables tools (such as indent and emacs) to display the source code correctly.

        if (something &&
            something_else) {

        if (something
        &&  something_else
        ) {

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

if (condition) break;

if (condition) {
        break;
}

        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;
        }

NUT codebase includes an .editorconfig file which should be supported by most of the IDEs and text editors nowadays. Many support this format specification (at least partially) out of the box, possibly with some configuration toggle in the GUI. Others may need a plugin, see more at https://editorconfig.org/#pre-installed page. There are also command-line tools to verify and/or enforce compliance of source files to configuration.

You can go a long way towards converting your source code to the NUT coding style by piping it through the following command:

indent -kr -i8 -T FILE -l1000 -nhnl

This next command does a reasonable job of converting most C++ style comments (but not URLs and DOCTYPE strings):

sed 's#\(^\|[ \t]\)//[ \t]*\(.*\)[ \t]*#/* \2 */#'

Emacs users can adjust how tabs are displayed. For example, it is possible to set a tab stop to be 3 spaces, rather than the usual 8. (Note that in the saved file, one indentation level will still correspond to one tab stop; the difference is only how the file is rendered on screen). It is even possible to set this on a per-directory basis, by putting something like this into your .emacs file:

;; NUT style

(defun nut-c-mode ()
 "C mode with adjusted defaults for use with the NUT sources."
 (interactive)
 (c-mode)
 (c-set-style "K&R")
 (setq c-basic-offset 3)  ;; 3 spaces C-indentation
 (setq tab-width 3))      ;; 3 spaces per tab

;; apply NUT style to all C source files in all subdirectories of nut/

(setq auto-mode-alist (cons '(".*/nut/.*\\.[ch]$". nut-c-mode)
                       auto-mode-alist))

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;
}

Current preference for suggesting changes is to open a pull request on GitHub for the https://github.com/networkupstools/nut/ project.

For some cases, small patches that arrive by mailing list in unified format (diff -u) as plain text attachments with no HTML and a brief summary at the top are easy to handle, but sadly also easy to overlook.

If a patch is sent to the nut-upsdev mailing list, it stands a better chance of being seen immediately. However, it is likely to be dropped if any issues cannot be resolved quickly. If your code might not work for others, or if it is a large change, your best bet is to submit a pull request or create an issue on GitHub.

The issue tracker allows us to track the patches over a longer period of time, and it is less likely that a patch will fall through the cracks. Posting a reminder to the developers (via the nut-upsdev list) about a patch on GitHub is fair game.

Patches should have some kind of unifying element. One patch set is one message, and it should all touch similar things. If you have to edit 6 files to add support for neutrino detection in UPS hardware, that’s fine.

However, sending one huge patch that does massive separate changes all over the tree is not recommended. That kind of patch has to be split up and evaluated separately, assuming the core developers care enough to do that instead of just dropping it.

If you have to make big changes in lots of places, send multiple patches — one per item.

If you change something that involves an argument to a program or configuration file parsing, the man page is probably now out of date. If you don’t update it, we have to, and we have enough to do as it is.

If you write a new driver, send in the man page when you send us the source code for your driver. Otherwise, we will be forced to write a skeletal man page that will probably miss many of the finer points of the driver and hardware.

The same remark goes for device entries: if you add support for new models, please remember to also complete the hardware compatibility list, present in data/driver.list.in. This will be used to generate both textual, static HTML and dynamic searchable HTML for the website.

Finally, don’t forget about fame and glory: if you added or substantially updated a driver, your copyright belongs in the heading comment (along with existing ones). For vendor backed (or sponsored) contributions we welcome an entry in the docs/acknowledgements.txt file as well, to track and know the industry players who help make NUT better and more useful.

It is nice to update the NEWS file for significant development to be seen as part of next release, as well as to update the UPGRADING file for potentially breaking changes and similar heads-up notes for third-party teams (distribution packagers, clients and bindings, etc.)

We currently use a Git repository hosted at GitHub to track changes to the NUT source code. This allows you to clone the repository (or fork, in GitHub parlance), make changes, and post them online for peer review prior to integration.

To obtain permission to commit directly to the common upstream NUT repository, you must be prepared to spend a fair amount of time contributing to the NUT codebase. Most developers will be well served by committing to their own forked Git repository (preferably in a uniquely named branch for each new contribution), and having the NUT team merge their changes using pull requests.

Git offers a little more flexibility than the svn update command. You may fetch other developers' changes into your repository, but hold off on actually combining them with your branch until you have compared the two branches (for instance, with gitk --all). Git also allows you to accumulate more than one commit worth of changes before pushing to another repository. This allows development to continue without a constant network connection.

For a quick change to a file in the Git working copy, you can use git diff to generate a patch to send to the nut-upsdev mailing list. If you have more extensive changes, you can use git format-patch on a complete commit or branch, and send the resulting series of patches to the list.

If you use GitHub’s web-based editor to make changes, it tends to create lots of small commits, one per change per file. Unless there is reason to keep the intermediate history, we will probably collapse (or "squash" in Git parlance) the entire branch into one commit with a git rebase -i before merging.

The GitSvnCrashCourse wiki page has some useful information for long-time users of Subversion.

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

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

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

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

The NUT repository generally only holds files which are not generated from other files. This prevents spurious differences from being recorded in the repository history.

If you add a driver, it is recommended that you add the driver executable name to the .gitignore file in that directory. Similarly, files generated from *.in and *.am source templates should be ignored as well. We try to include a number of generated files in the tarball releases with make dist hooks in order to minimize the number of dependencies for end users, but the assumption is that a developer can install the packages needed to regenerate those files.

From the git commit man page:

If your commit is just a change to one component, such as the HCL, upsd or a specific driver, prefix your commit message in a way that matches similar commits. This helps when searching the repository or tracking down a regression.

Referring to previous commits can be tricky. If you are referring to the immediate parent of a given commit, it suffices to say "the previous commit". (Are you correcting a typo in the previous commit? If you haven’t pushed yet, consider using the git commit --amend command instead of creating a new commit.) For other commits, even though tools like gitk and GitHub’s repository viewers recognize Git hashes and create links automatically, it is best to add some context such as the commit title or a date.

You may notice that some older commits have [[SVN:####]] tags and Fossil-ID footers. These were lifted from the old SVN commit messages using reposurgeon, and should not be used as a guide for future commits.

Please also note that since 2023 we explicitly ask for contributions to be "Signed Off" according to "Developer Certificate of Origin" as represented in the LICENSE-DCO file in the root of NUT source tree (verbatim copy of Version 1.1 of DCO published at https://developercertificate.org/ web site). This is exactly the same one created and used by the Linux kernel developers.

This is a developer’s certification that he or she has the right to submit the patch for inclusion into the project. Simply submitting a contribution implies this agreement, however, please include a "Signed-off-by" tag in every patch (this tag is a conventional way to confirm that you agree to the DCO). In other words, this tag certifies that committer has the rights to submit this work under the same license as the project and agrees to the terms of a Developer Certificate of Origin.

Note that while git commit hook tricks are available to automatically sign off all commits, these signatures are intended to be a conscious (legally meaningful) act — hence they are not automated in git core with an easy configuration option.

For more details see:

You are also encouraged to set up a PGP key, make its public part known, and use it to sign your git commits (in addition to the Signed-Off-By tag) by also passing a -S option or calling git config commit.gpgsign true once. Numerous public articles can walk you through this ordeal, including:

For developers who have commit access to the common upstream NUT repository: Please keep the Git "master" branch in working condition at all times. The "master" branch may be used to generate daily tarballs, it provides the baseline for new contributions, and occasionally is tagged for a new release. It should not contain broken code. If you need to commit incremental changes that leave the system in a broken state, please do so in a separate branch and merge the changes back into "master" once they are complete.

To help keep the codebase ever-green, we run a number of CI tests and builds in various conditions, including older compilers, different C/C++ standard revisions, and an assortment of operating systems; a section below elaborates on this in more detail.

You are encouraged to use git rebase -i on your private Git branches to separate your changes into logical changes.

From there, you can generate patches for the issue tracker, or the nut-upsdev mailing list.

Note that once you rebase a branch, anyone else who has a copy of this branch will need to rebase on top of your rebased branch. Obviously, this hinders collaboration. In this case, we recommend that you rebase only in your private repository, and push when things are ready for discussion. Merging instead of rebasing will help with collaboration, but please do not turn the repository history into a pile of spaghetti by merging unnecessarily. (Test merges can be done on integration branches, which can be discarded if the merge is trivial.) Be sure that your commit messages are descriptive when merging.

If you haven’t created a commit out of your local changes yet, and you want to fetch the latest code, you can also use git stash before pulling, then git stash pop to apply your saved changes.

Here is an example workflow:

        git clone -o central git://github.com/networkupstools/nut.git

        cd nut
        git remote add -f username git://github.com/username/nut.git

        git checkout master
        git branch my-new-feature
        git checkout my-new-feature

        # Hack away

        git add changed-file.c
        git commit -s

        # Fix a typo in a file or commit message:

        git commit -s -a --amend

        # Someone committed something to the central repository. Fetch it.

        git fetch central
        git rebase central/master

        # Publish your branch to your GitHub repository:

        git push username my-new-feature

If you are new to Git, but are familiar with SVN, some of the following links may be of use:

For a developer, the NUT build process starts with ./autogen.sh.

This script generates the ./configure script that end users typically invoke to build NUT. If you are making a number of changes to the NUT source tree, configuring with the --enable-maintainer-mode flag will ensure that after you change a Makefile.am, nearby Makefile.in and Makefile get regenerated. At a minimum, you will need at least:

Even if you do not use your distribution’s packages of NUT, installing the distribution’s list of build dependencies for NUT can reduce the amount of trial-and-error when installing dependencies. For instance, in Debian, you can run apt-get build-dep nut to install all of the auto* tools as well as any development libraries and headers.

After running ./autogen.sh, you can pass your local configuration options to ./configure and run make from the top-level directory. To avoid the need for root privileges when testing new NUT code, you may wish to use --prefix=$HOME/local/nut --with-statepath=/tmp. You can also keep compilation times down by only building the driver which you are currently working on: --with-drivers=driver1,dummy-ups.

Before pushing your commits upstream, please run make distcheck-light. This checks that the Makefiles are not broken, that all the relevant files are distributed, and that there are no compilation or installation errors. Note that unless you specifically pass --with-doc=skip to configure, this requires all of the dependencies necessary to build the documentation to be locally installed on your system, including asciidoc, a2x, xsltproc, dblatex and any additional XSL stylesheets.

Running make distcheck-light is especially important if you have added or removed files, or updated configure.ac or some Makefile.am file. Remember: simply adding a file to Git does not mean it will be distributed. To distribute a file, you must update the corresponding Makefile.am with EXTRA_DIST entry and possibly other recipe handling.

There is also make distcheck, which runs an even stricter set of tests than make distcheck-light, but will not work unless you have all of the optional third-party libraries and features installed.

Finally note, that since 2017 the GitHub upstream project is monitored by Travis CI (in addition to earlier multi-platform buildbots which occasionally do not work), replaced since 2021 by a dedicated NUT CI farm. This means that if your posted improvements are based on current NUT "master" branch, the resulting pull request should get tested for a number of scenarios automatically. If your code adds a substantial feature, consider extending the Jenkinsfile-dynamatrix and/or ci_build.sh scripts in the workspace root to add another BUILD_TYPE to the matrix of tests run in parallel.