This file describes how to build and use wnlib on Windows.

(There are two versions of this file, README.html and README.txt.  README.html is the master copy, README.txt is autogenerated from it).

Overview

This readme file is in the directory wnlib\windows.  If you've just unzipped this package, you will find the h, src, and examples subdirectories of this directory empty.  The selftest directory will contain a bunch of C files (they will look ugly in notepad at this point because they haven't been translated to DOS form yet).

The source for wnlib is in the directory ..\acc\*.  Keep out of there.  That area is for unix builds, we build in this separate area for windows.  The first thing you will have to do is copy the source from the windows to the windows area according to the following instructions.  (We didn't want to duplicate it in the zip file).


Copying the source from the unix area to the windows area

Go to the wnlib\windows directory and run copysrc.bat, just click on it in windows explorer.

- h directory should now contain about 80 wn*.h files
- src directory should now contain about 171 wn*.c files
- examples directory should now contain about 24 wnex_*.c files
- selftest directory should now contain about 24 *.c files which were already there before copysrc.bat ran
- ..\doc\mantext directory should now contain about 85 *.txt files, and main_man.html


Building your Application with wnlib

The following directions are for building with Microsoft Visual C++ 4.0.  It is assumed they will apply reasonably well to other environments.  We are interested in hearing about your successes/failures with other environments (see contact intormation below and in the wnlib\README file).
Build wnlib.lib
All the c files that are to be compiled into wnlib.lib are in the src directory.
- Start your workspace with "File" -> "New" -> "Project Workspace" -> "Static Library".
- Specify "wnlib" as the project name, and specify "location" as wnlib\windows\src.  (note you have to check on the location field, select it and right arrow to the end of the field, and backspace away any extra you don't want there).
- Then "Insert" -> "Files into Project", select all of the C files and click "add".
- Set your settings with "Build" -> "Settings".
- Go to the C/C++ tab, and select the category "preprocessor".
- Add "..\h" to the directories to be searched for include files.
- Go to the Library tab, and set the output file as "..\wnlib.lib"
- Build.
Build selftest_main.exe
All the C files to test wnlib.lib are in the selftest directory.
- Start your workspace with "File" -> "New" -> "Project Workspace" -> "Console Application".  Name it "selftest" in "wnlib\windows\selftest".
- Then "Insert" -> "Files into Project", select all of the C files and click "add".
- Set up the "Build" -> "Settings" like before, only specify that the program .\selftest_main.exe is to be built, and include "..\wnlib.lib" at the beginning of the objects/libs to be linked in.
- Build
- You can then execute the exectuable from the "Build" menu, or from the "Start" -> "Run" command.  If it finishes without crashing, your wnlib is in good health.  The philosophy of the selftest code is to run fairly silently as long as everything is OK, and crash if anything goes wrong.

Building your application with wnlib
Building your application is done basically the same way as building the selftest, making sure you set up "wnlib\windows\wnlib\h" in your C/C++ preprocessor include path and "wnlib\windows\wnlib.lib" in your Link objects/libraries field.

Summary of use
The library is wnlib\windows\wnlib.lib
h files are in wnlib\windows\h
Documentation is in wnlib\doc\mantext
Projects:
wnlib.lib: wnlib\windows\src\wnlib.*
selftest: wnlib\windows\selftest\selftest.*


Documentation

After you have run copysrc.bat, and only after that, you can look at the documentation in the ..\doc\mantext\main_man.html file with Internet Explorer or your favorite web browser.  Note that main_man.html is just a master documentation file, with links to the smaller text files (also viewable in your browser) in the same directory.
Using the Examples

There is also the wnlib\windows\examples directory.  It is full of wnex_*.c files.  It is a supplement to the main_man.html documentation, providing examples of use of the wnlib code.
The wnex_*.c files are all independent of each other, separate programs each containing a main(), that must be linked with wnlib.lib.  This means that if you want to run them on windows, you must use the gui of your C building environment to manually create a separate project/makefile for each one, and build them separately.  Also, unlike the selftest files, they produce a lot of output to stdout that must be manually read to see if they are executing correctly.  For these reasons, we have not only compiled but not linked them on Windows, and you may encounter a link error here and there.

You can find which example programs call the function you want to use by searching them with the search facility in Windows Explorer, or grep if you have one.


Functionality not supported on Windows
The true random numbers (wnrndt.h, wnrndt.c) are just too unix dependent and thus are not ported to Windows.  The wn_popen() and wn_pclose() functions were just leading to an unrecoverable Blue Screen of Death (requiring a reboot) whenever I tried to use them, so they are not available on Windows.  This problem may have been limited to the Microsoft Visual C++ 4.0 on ME we ported to, if anyone can get them to work on some other Windows compiler / platform combination, please let us know.  The code is in src\wnio.c, conditionally compiled out.


Versions Supported

At this point, we have ported wnlib to Microsoft Visual C++ version 4.0 on Windows ME.  We figure this means it should port to MSVC++ 6.0 on XP trivially.  Very little of the code involves operating systems calls, so a port to a new platform is generally pretty easy.  Furthermore, we have restricted ourselves to using only using C as of the ANSI/ISO 9899-1990 standard, so you'll have to dig up some really ancient or isoteric C compilers to  find one that can't handle this code.  wnlib has previously been ported to the VMS, Sun Solaris, Red Hat & SuSE Linux, hpux, and cygwin operating systems using the cc, acc, CC, gcc, & g++ compilers.


Cygwin

One free alternative to windows development is cygwin.  Look it up on the web at http://www.cygwin.com .  It is a free unix shell that runs under windows, that is you can have one or more cygwin windows running unix commands on your windows desktop while everything else remains running windows.

There is no support for it, that is, there is support, but it costs $10,000 for lifetime support, and $10,000 on a per-incident basis.  It has an X windows setup, but I recommend against using it - it worked for me for a few weeks, then quit working.  I re-downloaded cygwin, but it kept not working and I gave up and went back to using linux for graphics.

But even without the X windows, it can be quite useful.  You can use the unix compilers gcc and g++ on it to build wnlib and your programs, and create .exe files that can be run on Windows.  wnlib fully supports cygwin as a unix platform.  You can run emacs under cygwin, or just use your favorite windows editor to edit cygwin files.  This means you can do non-graphical C program development on Windows without having to buy a C development enviroment.

You have a choice of how much to download when you get Cygwin, and you get a pretty bare bones setup if you default everything.  One nice thing is it's easy to go back and ask for more incrementally if you need it.  It usually gives you the option of downloading source for what you get, say "no" if you want to save space.  I downloaded a ton of stuff, with source, and it all adds up to about 1 Gbyte, but you should be able to download a much smaller subset than that.


Author:    Bill Chapman