Debian Codegraph @

README

raw
1 Building Dieharder
2 ========================================================================
3
4 You MUST run ./autogen.sh FIRST. Then ./configure, make and so on
5 should work. Sorry, if I distribute it any other way some aspect of the
6 Gnu Build Tools breaks for some system. See INSTALL for more details.
7
8 ========================================================================
9
10 Author Contact Information:
11
12 Robert G. Brown
13 Duke University Dept. of Physics, Box 90305
14 Durham, N.C. 27708-0305
15 Phone: 1-919-660-2567
16 Fax: 919-660-2525
17 Email: [email protected]
18 URL: http://www.phy.duke.edu/~rgb
19
20 ========================================================================
21
22 Versioning
23
24 Versioning in dieharder has a very specific meaning. The major number
25 is bumped when a major project milestone is reached OR when a major
26 fundamental redesign takes place (something that happens roughly 3-5
27 times over the lifetime of any given project). The first minor is the
28 number of tests built into the current snapshot. The second minor is
29 bumped when e.g. a major change occurs within a release -- a bug is
30 fixed, a new feature (but not a new test) is added. Release is used to
31 track micro/testing releases in the development cycle. Basically,
32 proposed bugfixes that will eventually become bumps in the second minor
33 number.
34
35
36 In this way one can always see if dieharder is likely to have major new
37 features or bugfixes in it relative to your current version.
38
39 Notes About the Tests in Dieharder
40
41 Dieharder is original code written by and Copyright Robert G. Brown
42 (with different code modules written over the period 2003-present). The
43 tests included (or expected to be included in the future) in dieharder,
44 are, however, derived from descriptions from several places.
45
46 * Diehard, a famous suite of random number tests written over many
47 years by George Marsaglia. The original Diehard sources (written in
48 Fortran) are (of course) Copyright George Marsaglia according to the
49 Berne convention, where authors retain copyright with or without a
50 notice in any original work. The original Diehard code written by
51 Marsaglia did not include a copyright notice or an explicit license in
52 or with the sources that have been made publically available on the web
53 for many years. When contacted, Dr. Marsaglia has indicated his wish to
54 restrict commercial usage of his code and permit only academic/research
55 related use. For this reason the the algorithms are fully
56 re-implemented, in original code, in dieharder to keep authorship and
57 GPL licensing issues clear. However, all diehard-equivalent tests are
58 clearly labelled as such and academically attributed to Dr. Marsaglia.
59
60 * The National Institute of Standards and Technology (NIST)
61 Statistical Test Suite (STS) as described in publication SP800-22b.
62 Although this test suite was developed with government support and is
63 explicitly in the public domain, and is available in C source. There is
64 some overlap between STS and Diehard -- for example, both have binary
65 matrix rank tests -- but the STS focusses primarily on bitlevel
66 randomness and the suitability of a random number generator for use in
67 cryptographic applications. The tests described in SP800-22b that are
68 implemented in dieharder are completely rewritten in original C by
69 Robert G. Brown to keep copyright and GPL issues clear. All STS-derived
70 tests are clearly labelled as such and are academically attributed to
71 the various authors of the suite (Andrew Rukhin, Juan Soto, James
72 Nechvatal, Miles Smid, Elaine Barker, Stefan Leigh, Mark Levenson, Mark
73 Vangel, David Banks, Alan Heckert, James Dray, San Vo).
74
75 * Original tests or timing operations inserted by Robert G. Brown.
76 Almost any distribution that can be computed on the basis of a source of
77 random numbers with a derived statistic with known or reliably
78 measurable statistical properties can serve as a test of random numbers
79 using the general approach implemented in Diehard, the STS, Dieharder,
80 and elsewhere.
81
82 * Tests described in Knuth's The Art of Computer Programming.
83
84 * User-contributed tests.
85
86 * Tests described elsewhere in the literature.
87
88 In all cases some effort has been made to correctly attribute the
89 originator of a test algorithm, and if there are any errors in this
90 regard they will be happily corrected once they are brought to the
91 attention of the author.
92
93 ========================================================================
94
95 To Build Dieharder
96
97 See the file INSTALL that should have come with the tarball to get
98 fairly explicit building instructions. You may have to experiment a bit
99 to figure out the dynamic linking thing mentioned there and below in
100 order to be able to hack the library and the front end at the same time.
101
102 Development and Experimentation
103
104 Dieharder is an open source project for a reason -- it simply is not
105 possible to trust a test suite of this sort without access to the source
106 because even a subtle error in the sources or data used to perform a
107 test will cause the test to return incorrect answers, conceivably to the
108 detriment of all concerned. With the source readily available, any user
109 is free to examine or modify the source for any test and determine
110 whether or not the test is working and participate in the critical
111 process whereby academia arrives at a consensus truth.
112
113 Also, many individuals may wish to use the general dieharder library to
114 test their own (software) rngs. This may well involve adding tests or
115 modifying individual tests already there, or dieharder defaults.
116 dieharder is built using the familiar, if somewhat evil, Gnu Build
117 Tools. Unpack tarball, run autogen.sh, ./configure, make. If you wish
118 to install, be sure to set the prefix. Be aware that this program
119 builds a DYNAMICALLY LINKED version of the program. If you want a
120 statically linked version or to be able to work on it in the build
121 directory either add the libdieharder directory to your
122 LOAD_LIBRARY_PATH or hack the Makefile.am to build and use a static
123 library (the commands are there, commented out).
124
125 RPM
126
127 Dieharder is developed on RPM-based systems (FCX) and one should be able
128 to build an RPM by using the make target: "make rpm" (after setting up
129 a private RPM build tree). No root privileges are needed to build the
130 rpms in this way.
131
132 Debian / Ubuntu
133
134 Dieharder has been in Debian since February 2007. Therefore, on most current
135 Debian or Ubuntu systems a simple
136
137 sudo apt-get install dieharder
138
139 installs the command-line (which itself also install the shared library
140 package it depends upon). In order develop against the Dieharder API, run
141
142 sudo apt-get install libdieharder-dev
143
144 ========================================================================
145
146 Licensing and Revision Control
147
148 Dieharder is (as noted) Copyright Robert G. Brown, 2003-2006. It has
149 been kept under revision control (first CVS, more recently Subversion)
150 since the inception of the process in 2003 and all incremental changes
151 to the code as it was developed are carefully documented.
152
153 Dieharder was deliberately developed to be a GPL project, since
154 alternative random number test suites were either incomplete with regard
155 to the span of test possibilities of interest to the author, restricted
156 or unclear about their licensing restrictions, or both. In addition, by
157 integrating from the beginning with the Gnu Scientific Library (which is
158 a full GPL project with the viral version of the license) it becomes
159 itself a GPL project in any event.
160
161 It is strongly suggested that prospective users of this test read the
162 terms of the license included with this source distribution in the file
163 COPYING. In summary, permission is granted to freely use and modify the
164 sources and distribute the result or any binary objects derived
165 therefrom as long as the terms of the GPL are abided by. These terms
166 require the preservation of all copyright and license information in the
167 sources and that the source of any and all revisions to the original
168 dieharder code be made available upon request to any receivers of a
169 dieharder binary, among other things.
170
171 This program is distributed in the hope that it will be useful, but
172 WITHOUT ANY WARRANTY; without even the implied warranty of
173 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
174 General Public License for more details.
175
176 If any user of the dieharder program should revise the program in a way
177 that is likely to be of use to others, they are encouraged to at least
178 offer to contribute the revision back to the project (subject to the
179 "editorial" approval of the primary author). Contact Robert G. Brown to
180 arrange for such a contribution.
181
182 ========================================================================
183
184
185