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