1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
|
NUT for Windows Installer
=========================
This component aims to provide an integrated installer for NUT on Windows,
including registration as the preferred handler of certain USB vendor and
product identifiers.
Various waves of the NUT for Windows effort happened over the decades, with
the latest one being integration of the platform-specific source code which
was previously available in side projects, into the main Network UPS Tools
project and its continuous-integration builds, between NUT v2.8.0 and v2.8.1
releases (over 2022-2023 time frame).
NOTE: This document aims to revive institutional knowledge about producing
a NUT for Windows installer file. Currently builds of NUT for Windows are
quite possible, they can result in preparation of a tarball of an installed
directory tree which is immediately usable on Windows. However, separate
steps may be needed for USB specifically (so that NUT drivers and not the
default "HID Battery" handler can attach to the device) and for OS Service
integration. It is assumed that the installer would handle these rituals.
Prerequisites for building NUT for Windows
------------------------------------------
Please see the documentation provided with the NUT sources about prerequisites
needed for semi-native builds (on Windows using MinGW x64 and MSYS2 projects)
and cross-builds (on Linux with mingw64 packages):
* linkdoc:qa-guide[Prerequisites for building NUT on different
OSes,NUT_Config_Prereqs,docs/config-prereqs.txt]
* linkdoc:scripts/Windows/README.adoc[]
With these dependencies in place, the common NUT `ci_build.sh` script can be
used to wrap the typical configuration, build and installation procedures.
Similar results can be of course achieved by direct use of the `configure`
script, which may be the way to go particularly for customized builds.
See also `scripts/Windows/build-mingw-nut.sh` for the cross-build wrapper
details.
Prerequisites for building the installer
----------------------------------------
NUT for Windows uses the WiX Toolset to codify and implement the installer:
* https://wixtoolset.org/
* https://wixtoolset.org/docs/intro/
* https://wixtoolset.org/docs/tools/wixexe/
* https://wixtoolset.org/docs/tools/heat/
* link:https://wixtoolset.org/docs/v3/overview/candle/[candle.exe] and
link:https://wixtoolset.org/docs/v3/overview/light/[light.exe] tools
were used in current scripts (dating from 2013) but were obsoleted
after WiX v3 and became part of `wix.exe` according to
https://wixtoolset.org/docs/fourthree/ update notes
* https://github.com/wixtoolset/
* https://github.com/wixtoolset/wix/
The toolset in turn requires the .NET framework (and the related NuGet tool)
which is available on Windows and Linux platforms, at least. In case of the
latter (for cross-builds) note that many of the newer distribution releases
should include dotnet packages in their repositories; for earlier releases
a Microsoft repository can be added -- as detailed in their documentation:
* https://learn.microsoft.com/en-us/dotnet/core/install/linux
* https://dotnet.microsoft.com/en-us/download
* https://www.nuget.org/downloads
For example, on Ubuntu the installation can be performed like this:
----
:; sudo apt-get update && \
sudo apt-get install -y dotnet-sdk-7.0 nuget
----
NOTE: For installation on Ubuntu 20.04 and older, where an additional
package repository is required, please see instructions at
https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu-2004
Subsequent installation of the toolset on either platform would be:
----
:; dotnet tool install --global wix
----
Maintaining the recipes and building the installer artifact
-----------------------------------------------------------
NOTE: To be investigated, modernized and completed per
https://github.com/networkupstools/nut/issues/1485
Files were not touched considerably since 2013 (or earlier?) and would
likely need deeper investigation and update to be useful. Findings so far:
- Directory `scripts/Windows/DriverInstaller` contains a helper
program (currently named `wdi-simple`) for driver installation
- Directory `scripts/Windows/Installer` (with this document) contains
the batch file script to call WiX tools (currently geared for WiX v3
or older) and the XML file which describes the installer actions and
the file/directory structures it would deliver.
* It would be helpful to find how to generate the filesystem structure
(names, `GUID`s, what else?) based on the prototype area prepared by
`make install DESTDIR=...` during a NUT build. It does not have to
be part of *every* build (e.g. we can want this separated by driver
types to allow end-users to install just a subset of NUT, similar
to how this happens with multi-package approach on Unix/Linux) but
an automated process which makes maintenance easier would be great:
let a human sort where different filenames are categorized, and let
automation discover that some installed files are not mentioned or
some listed files are not present.
- Directory `scripts/Windows/Installer/ImageFiles` contains various
resources used by the installer, including apparently `Others/` for
third-party files and `emptyDir` as a target for NUT `make install`?
* This may be moderately compatible with what the Makefile driven
installation does with current codebase -- especially how it pulls
third-party library DLL files into the prototype install area.
- The `scripts/Windows/wininit.c` program provides a rough equivalent
to POSIX init scripts, to wrap various NUT daemons as a single unit.
Its git history saw several re-architecting decisions, so if there
are any concerns if the current version does "the right thing", we
have some precedent ideas to look at. To a lesser extent, similar
code might have appeared and disappeared in the Windows-branch code
of daemons like `upsd` and `upsmon` before it condensed in this one.
The batch file and the XML manifest currently list a few libraries from
msys/mingw (as of back when this was coded). Current Makefile recipes
take a more active approach by walking the dynamic dependencies of the
built NUT binaries to copy those from the build environment.
The batch file takes care to pass sample configuration and documentation
files through `unix2dos` -- keep this in mind for new implementations.
|
