1 2 libcsc 3 Programmers' Resource Library 4 5 <http://sourceforge.net/projects/hackerlabs> 6 <http://hackerlabs.sourceforge.net> 7 8 Douglas R. Jerome 9 <jerome@globalcrossing.net> 10 <djerome@users.sourceforge.net> 11 12 13 14========== 15Disclaimer 16========== 17 18caveat: This file was written by a nerd engineer type. It may not be easy to 19 read or understand. You will, no doubt, find sentences that aren't. 20 My writing style is modeled on: "This is an incomplete. sentence." 21 22 23 24=========== 25Description 26=========== 27 28This is a distribution of libcsc, a "Programmers' Resource Library". That's a 29gandiose name. I don't really mean to imply much by the name; I just have a 30hard time thinking up good names. 31 32This library is an upgrade of the previous libcsc. The upgrade simplifies many 33functions and supports threadsafe capability. 34 35libcsc contains functions implementing general subsystems. By subsystem, I 36mean an abstract data type, or a poor man's object. What this really means in 37code is, for a hash table as an example, all the hash table functions are in 38the same .c source file with the appropriate parts hidden away (static) from 39the user of the hash table functions during link time. All exportable 40definitions and constants that the client of the hash table functions would 41want are in a .h file. 42 43Not everything in libcsc is part of something so conceptually complete that it 44all should legitimately be part of some subsystem. But, everything in libcsc 45is a part of some group, and I call these groups subsystems. 46 47Some things might be put into libcsc because they're reusable functionality 48which are (hopefully) reinforced with debug aids. Typically, the debug aids 49are just a bunch of assertions. 50 51libcsc currently contains these subsystems: 52 53 file in libcsc/src functionality 54 ------------------ ------------- 55 config-main.c ................. main program prints libcsc configuration 56 csc_config.c .................. libcsc configuration functions 57 csc_file.c .................... file/path name subsystem 58 csc_hash.c .................... hash table subsystem 59 csc_io.c ...................... general I/O functions 60 csc_list.c .................... general list (queue/stack) subsystem 61 csc_math.c .................... some math functions 62 csc_mem.c ..................... dynamic memory allocation functions 63 csc_notify.c .................. notification subsystem 64 csc_sock.c .................... BSD socket functions 65 csc_string.c .................. string handling functions 66 csc_symbol.c .................. symbol structure managing function 67 csc_symtab.c .................. symbol table subsystem 68 csc_sys.c ..................... general system functions 69 csc_timer.c ................... simple stopwatch timer functions 70 csc_tree.c .................... balanced binary tree subsystem 71 xcsc_debug.c .................. hidden assertion helper functions 72 73It is the goal of libcsc to implement bug catching features in commonly used 74functionality and thereby provide a common, reusable base for constructing 75solid applications. 76 77For efficiency sake, libcsc can be compiled without DEBUG (see INSTALLATION 78below) and continue to be used for its reusable subsystems. I use two versions 79of libcsc, one standard (actually with optimization) and one debug. I use the 80debug version for application development, and then relinked the application to 81the standard, nondebug version of libcsc for distribution. 82 83 84 85============ 86Requirements 87============ 88 89- ANSI Compliant Compiler 90- ANSI C Library 91- BSD Socket Subsystem 92 93 The libcsc code is mostly developed with strict ANSI compliance 94 enforced by the compiler, not by my knowledge of ANSI. The compilation 95 command lines containing the ANSI compliance switches are in my 96 makefiles (which are the makefiles that are in this distribution). 97 98 libcsc uses the BSD socket subsystem and won't completely build without 99 it. Without your compilation and runtime system having a BSD socket 100 subsystem you'll probably get a libcsc.a when you build it, but it 101 won't have its own BSD socket subsystem. 102 103 With any modern system the above requirements shouldn't be any problem. 104 If you run into other things, email me about it and I'll do my best to 105 fix it up. 106 107 108 109=========== 110Directories 111=========== 112 113This distribution should have these directories: 114 115 directory contents 116 --------- -------- 117 bin libcsc-config executable appears in here 118 doc manpage-like docs, reference manual maybe 119 include client accessible header files live here 120 lib libcsc.a and libcsc.o appears in here 121 src libcsc *.c source code lives here 122 t unix-targeted test programs live here 123 tools miscellaneous scripts (for building libcsc) live here 124 125 126 127============= 128Documentation 129============= 130 131BUGFORM ....... Use this to send bug reports. Please do use it. 132 133BUGS .......... List of known bugs. 134 135CHECKSUMS ..... A list of checksums for the source code. 136 137COPYRIGHT ..... The LGPL. 138 139CREDITS ....... List of people that I know have contributed to libcsc. 140 141ERRATA ........ List of known limitations. To do list. List user visible 142 changes from the version to version. 143 144FAQ ........... Frequently Asked Questions. 145 146INSTALL ....... Description of libcsc, build and installation instructions, and 147 some lame troubleshooting tips. 148 149LICENSE ....... LGPL 150 151README ........ Quick notes, if any. 152 153doc/reference.manual .......... Technical reference / programming guide for 154 libcsc. 155 156doc/man? ...................... Man page-like files for the libcsc functions 157 and subsystems. 158 159 160 161============ 162INSTALLATION 163============ 164 165******* 166******* Read the BUGS/ERRATA file. 167******* 168 169Unpack the libcsc library tarball, libcsc-x.x.x.tar.gz. You can use these 170commands: 171 172 gunzip libcsc-x.x.x.tar.gz 173 tar xf libcsc-x.x.x.tar 174 175If for some strange reason you don't have the tarball, you can get it at: 176 177 http://sourceforge.net/projects/hackerlabs 178 179<LIBCSC> is used below to designate the directory created when you unpacked the 180libcsc-x.x.x.tar.gz tarball. 181 182NOTE This all works with gcc on Linux. That's all I have access to. 183 184I highly recommend building and installing the libcsc compiled with the DEBUG 185macro defined. When libcsc is built for debugging, it will help you catch 186bugs; I hope. This library is loaded with assertions and data checks that are 187only enabled when built for debugging. After you are comfortable with your 188application (and libcsc), relink your application with the standard, nondebug 189version of libcsc. Build the debug version of libcsc by defining the macro 190DEBUG on the make command line: 191 192 make CDEBUGFLAGS=-DDEBUG 193 194To build with debugger information, or, conversly, to build with a high level 195of optimization, one can conveniently use the CC_PARAMS macro on the make 196command line, like this: 197 198 make CC_PARAMS=-g # build with debugger option 199 make CC_PARAMS=-O3 # build with high level of optimization 200 201Build libcsc 202------------ 203 204OPTION You have the option to just dive into the various libcsc makefiles and 205 build it the way you want. 206 207 I haven't yet learned better. I expect as much hacking to take place 208 on libcsc's makefiles as on its source code. If you use libcsc then 209 you might (should) look into the makefiles and understand what it is 210 that you can do with CDEBUGFLAGS and CC_PARAMS. 211 2121. Go to the <LIBCSC> directory and type the following at your shell 213 prompt (to make the library with debugging instrumentation and symbols 214 highly suggested): 215 216 cd src 217 make CDEBUGFLAGS=-DDEBUG CC_PARAMS=-g 218 219 or if you want to make the library without the DEBUG code and with 220 optimization: 221 222 cd src 223 make CC_PARAMS=-O3 224 2251.5. You now have libcsc.a and libcsc.o sitting in <LIBCSC>/lib. There 226 probably also is libcsc.a.names and libcsc.o.names in the src 227 directory; these are the corresponding symbol tables. 228 2292. You can use libcsc from its current location. Simply add 230 <LIBCSC>/include to your compilation include path, add <LIBCSC>/lib to 231 your link library path, and link your application with a -lcsc flag. 232 233Install libcsc 234-------------- 235 236 You might have to be a privileged user (root) to do this. Remember, 237 you can change the install location in the makefile; see step 1. 238 2391. The default installation directory is /usr/local. The library is 240 installed into /usr/local/lib (INSTALLLIB in the makefile), and the 241 header files are installed into /usr/local/include (INSTALLINC in the 242 makefile). These directories might need to already exist. If you 243 want to change the default install location you can edit 244 <LIBCSC>/src/Makefile. 245 2462. Install the libcsc header files and library: cd into <LIBCSC>/src, 247 type the following into your shell prompt: 248 249 make install 250 251 This will put the libcsc header files into /usr/local/include and put 252 libcsc.a and libcsc.o into /usr/local/lib (if you haven't changed a 253 default installation directory). 254 255Summary 256------- 257 2581. For the debug version of libcsc (HIGHLY recommended): cd into 259 <LIBCSC>/src, type the following into your shell prompt: 260 261 make CDEBUGFLAGS=-DDEBUG CC_PARAMS=-g 262 make install 263 264 You will have (where <INSTALL> is the installation directory which 265 is defaulted to /usr/local): 266 267 <INSTALL>/include/*.h 268 <INSTALL>/lib/libcsc.a 269 <INSTALL>/lib/libcsc.o 270 2712. For the standard, nondebug version of libcsc: cd into <LIBCSC>/src, 272 type the following into your shell prompt: 273 274 make CC_PARAMS=-O3 275 make install 276 277 You will have (where <INSTALL> is the installation directory which 278 is defaulted to /usr/local): 279 280 <INSTALL>/include/*.h 281 <INSTALL>/lib/libcsc.a 282 <INSTALL>/lib/libcsc.o 283 284 285 286=========================== 287How to Make a gdb Backtrace 288=========================== 289 290Backtraces can help me fix bugs that make applications crash. If you find a 291bug that crashes an application, please send a backtrace with your bug report. 292 293To make a useful backtrace, you need a core file with debugging information 294produced by the application when it crashes. 295 296When it does crash, type the following from your shell: 297 298 script 299 gdb <application> core 300 301Then, in the gdb prompt type "bt". Blammo, you've got the backtrace in front 302of you. Quit from gdb by typing "quit", then in the shell prompt type "quit". 303The file named typescript will contain the backtrace. 304 305 306 307========== 308Copyrights 309========== 310 311The "Reference Manual for libcsc", if any, is OWNED and copyrighted by 312Douglas R. Jerome and is LICENSED through the GNU Free Documentation License. 313The "Reference Manual for libcsc", if any, and its license can be found in the 314doc directory of this distribution. 315 316libcsc is OWNED and copyrighted by Douglas R. Jerome and is LICENSED (read the 317LICENSE file) through the GNU Library General Public License. Read the 318COPYRIGHT file for the complete license. 319 320 I don't really care what you do with these files; I only would like 321 some credit for the work I did on them (read the LICENSE file). 322 323[eof] 324