forked from lclevy/ADFlib
-
Notifications
You must be signed in to change notification settings - Fork 1
/
INSTALL
202 lines (141 loc) · 6.29 KB
/
INSTALL
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
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
General information
--------------------
There are 2 buildsystems that can be used - CMake and autotools (links below).
Obviously, a requirement for building is installation of the chosen one.
Testing require also the Check testing framework for C (link below).
Building deb packages require typical tools for that (ie. helper script uses
debuild from devscripts).
Building with CMake
--------------------
There are helper scripts in the util/ directory, which should help doing quick
builds. For instance, to build a release version (both static and binary lib.):
1. $ util/cmake_release_configure
2. $ util/cmake_release_build
Debug version (with gdb and address sanitizer, where available...) can be built
in the same way, just replace "release" with "debug" in the commands above.
To clean the build subdirectory use:
$ util/cmake_clean
(all have to be configured again for building).
Native device type (generic(dummy) vs. real physical linux/win32 devices) can
be selected by setting ADFLIB_ENABLE_NATIVE_DEV option (to ON or OFF).
For instance:
$ util/cmake_shared_configure -DADFLIB_ENABLE_NATIVE_DEV:BOOL=ON
would configure build with shared library and support for the real, physical
devices.
Currently, by default only cmake_debug_configure enables real, native devices.
At this stage, if you are not testing (caution, real, physical storage/disk
devices in use!) - use the default: generic (a safe dummy device).
Other options allow to build with or without tests:
ADFLIB_ENABLE_TESTS, ADFLIB_ENABLE_UNIT_TESTS
and build with or without the address sanitizer (normally used only for
debugging/sanitizing memory problems): ADFLIB_ENABLE_ADDRESS_SANITIZER
Building with Autotools
------------------------
Standard way:
1. $ ./autogen.sh
2. $ ./configure
or better (see the warning below):
$ ./configure --enable-native-generic
3. $ make
Native devices can be selected with configure script switches:
--enable-native-generic Enable generic native devices
--enable-native-linux Enable Linux native devices
--enable-native-win32 Enable Win32 native devices
WARNING: the native device type selected by default by autotools is the one
NATIVE FOR THE HOST OS(!), so using physical storage (disk)
devices(!). At this stage, if you are not testing this functionality
in a safe environment (like a VM), it is strongly advised to build
only a generic/dummy native device.
Building with Visual Studio
----------------------------
Existing CMake configuration should allow to build with VS. Just open
the directory with the project (or possibly clone the repo with VS).
It should configure automatically, and it can be build as usual ("Build all").
There are 2 debug and 2 release configurations for VS, allowing to build
a static or a shared (DLL) library. All use MSVC compiler (but this can be
changed easily in CMake settings, eg. to clang ).
Building Debian packages
-------------------------
To build a .deb package for Debian (or any derivative), use the helper script:
$ util/deb_build.sh
In the parent(!) directory (to that of the project), it will create:
- a source package (.tar.gz)
- binary packages (.deb)
The source package alone can be created with:
$ util/deb_create_quilt3_archive.sh
Testing
--------
There are 3 sets of tests:
- regtests/ - contain regression and some functional tests (with test data,
like adf images)
- tests/ - mainly unit tests; require Check testing framework (link below)
- examples/tests/ - contains some basic tests of the command-line tools
Note that:
- on Windows (Visual Studio, CygWin) tests with shared library will fail,
unless the built library (src/adf.dll, cygadf.dll for CygWin) is copied
to the directories with test binaries (it probably can be fixed and done
automatically but no time for it now; if sb has good solution for this,
help welcomed).
Testing with CMake
-------------------
After successful building (see above), automatic tests can be started with:
$ util/cmake_debug_test (to test debug version)
$ util/cmake_shared_test (for the shared library version)
$ util/cmake_static_test (for the static library version)
Testing with Autotools
-----------------------
After successful building (see above), automatic tests can be started with:
$ make check
Testing with Visual Studio
---------------------------
"Run CTests".
Note that:
- tests using shell scripts does not work - they require sh / bash
(can be installed and configured but not a standard thing on Windows...)
Installation
-------------
... was not much used / tested. Except for deb packages (which build and
install fine on current Debian stable and on Ubuntu in GitHub Actions).
Basic checks are done by the CI system for CMake and autotools on Linux
(Debian and Ubuntu) and MacOS, so those should work fine.
Installation with CMake
------------------------
(Note that this was not much used / tested!)
To default location:
$ util/cmake_release_install
To a custom location:
$ util/cmake_release_install [custom_prefix]
To install one version of the library (static or shared):
$ util/cmake_shared_install
$ util/cmake_static_install
Installation with autotools
----------------------------
To a configured location:
$ make install
To change default location, do:
$ ./configure --help
and look for prefix options.
Installation with Visual Studio
--------------------------------
Find produced DLL and EXE and copy wherever you want...
(btw. not sure what CMake install does on Windows...)
Cross-compilation (an example)
-------------------------------
Building for Windows can be done cross-compiling eg. on Linux with MinGW:
$ CC=i686-w64-mingw32-gcc util/cmake_shared_configure
or just use:
$ util/cmake_shared_configure_cross_mingw
and then normally:
$ util/cmake_shared_build
Note that the tests will not work for rather obvious reasons - .EXE and .DLL
are not for Linux...
Most likely, it is possible to run the tests eg. using some Windows emulation
like Wine. The executables should work of course, but the testing suites will
require eg. configuring Windows CMake or tinkering test configuration to use
Wine for execution etc...
It should rather be tested and used on the native target system.
Links
------
- CMake: https://cmake.org/
- autotools: https://en.wikipedia.org/wiki/GNU_Autotools (and links there)
- Check: https://libcheck.github.io/check/