README
1======================================
2 Module "Bit::ShiftReg" Version 2.0
3======================================
4 for Perl version 5.000 or higher
5
6
7Contents of this file:
8----------------------
9
10 - Legal stuff
11 - Requirements
12 - What does it do
13 - Preliminary steps for use with Perl prior to version 5.002
14 - How to install it
15 - Version history
16 - Credits
17 - Final note
18
19
20Legal stuff:
21------------
22
23Copyright (c) 1997 by Steffen Beyer. All rights reserved.
24This package is free software; you can redistribute it
25and/or modify it under the same terms as Perl itself.
26
27
28Requirements:
29-------------
30
31Perl version 5.000 or higher, a C compiler capable of the ANSI C standard (!)
32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
33
34
35What does it do:
36----------------
37
38This module implements rotate left, rotate right, arithmetic shift left
39and logical shift right operations with carry flag for all C integer types.
40
41The results depend on the number of bits that the integer types unsigned
42char, unsigned short, unsigned int and unsigned long have on your machine.
43
44The module automatically determines the number of bits of each integer type
45and adjusts its internal constants accordingly.
46
47
48Preliminary steps for use with Perl prior to version 5.002:
49-----------------------------------------------------------
50
51Edit the file "Makefile.PL" in this distribution and change the line
52
53 'VERSION_FROM' => 'ShiftReg.pm',
54
55to
56
57 'VERSION' => '2.0',
58
59Then edit the file "ShiftReg.pm" and change the line
60
61 bootstrap Bit::ShiftReg $VERSION;
62
63to
64
65 bootstrap Bit::ShiftReg;
66
67Finally, edit the file "ShiftReg.xs" and delete the line
68
69 PROTOTYPES: DISABLE
70
71
72How to install it:
73------------------
74
75Please unpack and build this package OUTSIDE the Perl source and distribution
76tree!!
77
78 1) Change directory to the directory that has been created by unpacking this
79 package ("Bit-ShiftReg-2.0/").
80
81 2) Type "perl Makefile.PL" (or whatever the name and path of your Perl 5
82 binary is).
83
84 This will create a "Makefile" with the appropriate parameters for your
85 system (for instance, where the install directories are, and so on).
86
87 3) Type "make".
88
89 This will create a dynamically linkable library file that will be linked
90 to Perl later, at runtime, provided your system supports dynamic linking.
91
92 Please refer to the MakeMaker documentation for instructions on how
93 to build a new Perl with statically linked libraries (invoke "perldoc
94 ExtUtils::MakeMaker" for this), if your system does NOT support dynamic
95 linking!
96
97 Should you encounter any compiler warnings or errors (like the redefini-
98 tion of certain types already defined by your system), please contact
99 me by mail at <sb@sdm.de>, sending me your compiler output (both STDOUT
100 and STDERR). Thank you!
101
102 ======================================================================
103 Be aware that you need a C compiler which supports ANSI C in order to
104 successfully compile this package!
105 ======================================================================
106
107 Also note that problems may arise with the c89 compiler of HP, although
108 it allegedly supports ANSI C!
109
110 I recommend the GNU gcc compiler, which is available for free on the
111 Internet.
112
113 (HP users are strongly recommended to install the GNU assembler GAS
114 first before installing GNU gcc)
115
116 Should you get the error messages
117
118 ShiftReg.c: 15: Unable to find include file 'EXTERN.h'.
119 ShiftReg.c: 16: Unable to find include file 'perl.h'.
120 ShiftReg.c: 17: Unable to find include file 'XSUB.h'.
121
122 then edit the file Makefile.PL and change the line
123
124 'INC' => '', # e.g., '-I/opt/pkg/perl5.003/dist'
125
126 in such a way that it points to your Perl 5 distribution tree, e.g.,
127
128 'INC' => '-I/usr/ctr/dlt/private/perl/perl5.003',
129
130 or the like, and start over with the generation of the Makefile at 2).
131
132 4) Now issue "make test".
133
134 The output should look somewhat like this:
135
136 PERL_DL_NONLAZY=1 /usr/bin/perl -I./blib/arch -I./blib/lib
137 -I/e/www/sw/pkg/perl/lib/i386-freebsd/5.003 -I/e/www/sw/pkg/perl/lib
138 -e 'use Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;'
139 t/*.t
140 t/f000..............ok
141 t/f001..............ok
142 t/f002..............ok
143 t/f003..............ok
144 t/f004..............ok
145 t/f005..............ok
146 t/f006..............ok
147 t/f007..............ok
148 All tests successful.
149 Files=8, Tests=234, 1 secs ( 1.40 cusr 0.23 csys = 1.63 cpu)
150
151 5) At last, type "make install".
152
153 6) Share and enjoy!
154
155
156Version history:
157----------------
158
159Version 1.0 was the initial release.
160
161Version 1.1 fixed a possible bug in the XS file where the number of bits
162of an unsigned char was assumed to be 8 bits (without even checking) in
163the previous version.
164
165Version 2.0 provides new "MSB" and "LSB" functions (for all types).
166
167This version also changed the module's name from "ROL_ROR" to "Bit::ShiftReg".
168
169It also provides testing routines so that "make test" now works.
170
171And last but not least this version changed the interfaces of the existing
172functions so that they can be chained to form ever larger shift registers.
173
174
175Credits:
176--------
177
178Many thanks to Andreas Koenig <andreas.koenig@mind.de> (as always!)
179for his relentless support and efforts as upload manager of the CPAN!
180
181Also many thanks to Jon Orwant <orwant@media.mit.edu> and Tim Bunce
182<Tim.Bunce@ig.co.uk> for their suggestions concerning this module's
183name and its implementation!
184
185
186Final note:
187-----------
188
189If you need any assistance or have any comments, problems, suggestions,
190findings, complaints, questions, insights, compliments or donations to give ;-)
191then please don't hesitate to send me a mail:
192
193sb@sdm.de (Steffen Beyer)
194
195Yours sincerely,
196--
197 _____ _____ .__
198 _/ ____\____ _/ ____\____ |__|______
199 \ __\\__ \\ __\/ \| \_ __ \ Steffen Beyer
200 | | / __ \| | | | \ || | \/ sb@sdm.de
201 |__| (____ /__| |___| /__||__| sb@en.muc.de
202 \/ \/ http://www.engelschall.com/u/sb/
203