All of this stuff is covered in much more detail in the offline documentation.
The drive you install on must be an NTFS drive because CIDLib uses only long file names.
Once you've unzipped the file, you will have these major directories:
Here are the essential contents of that file:
SET CIDBUILD=Dev IF "%1"=="Prod" GOTO SET_PROD IF "%1"=="prod" GOTO SET_PROD IF "%1"=="PROD" GOTO SET_PROD GOTO DO_WORK :SET_PROD SET CIDBUILD=Prod :DO_WORK SET PATH=%PATH%%CIDDRIVE%\CID_Dev\%CIDBUILD%;%CIDDRIVE%\CID_Dev\Source\Cmd; SET _NT_SYMBOL_PATH=%CIDDRIVE%\CID_Dev\%CIDBUILD% SET CIDLOCALLOG=%CIDDRIVE%\CID_Dev\%CIDBUILD%\Log.Text SET CIDLOGSEM=CIDLib.Logging.Mtx SET CIDERRDUMPDIR=%CIDDRIVE%\CID_Dev\%CIDBUILD%\This file takes a parameter that indicates whether you want to set up to use the debug build or the production build. If no parameter is given, then the debug build is assumed. If the parameter is 'prod' or 'PROD', then the environment is set up for the production build. This parameter is used to set the CIDBUILD variable to either 'Dev' or 'Prod'. CIDBUILD is, in turn, used in all of the paths set, to indicate which build you want to work with.
First this file adds the CIDLib output directory to the PATH so that the programs built during the build can be run easily. According to the parameter you passed it adds either the debug output directory or the production output directory. It also adds the Cmd directory to the path also. So, after you run this file, you can run the other Cmd files without providing a full path.
Next it sets the _NT_SYMBOL_PATH variable to pointer to the output directory. This allows the CIDLib stack dump mechanism to find symbolic output. When a severe error is logged, the CIDLib system will do a runtime or exception error dump and it uses this symbolic information to provide method names in this stack dump.
The next two lines set up two standard CIDLib environment variables that the standard logging mechanisms use. CIDLib supports a very nice logging framework. When it is set up to log to some shared resource (like a file in this case) you need to tell it where to log, and it needs to be able to synchronize the output from multiple processes so they don't interfere with each other. CIDLOCALLOG sets the name of the file to log to and CIDLOGSEM is the name of a mutex that it will use to synchronize multiple process output. This is a major simplification of the logging system, but its fine as a default scheme.
The next line sets up an optional variable that tells CIDLib where to put error dump files. When a program crashes, CIDLib will trap this and output an extensive error dump file. If this variable is not set, then the file will go to the current directory of the program. Otherwise, it is output to the directory given by this variable. The file will be named xxx_pp.ErrorInf, where xxx is the name of the executable and pp is the process id of the instance of the program that died.
Keep in mind that the programs that you debug or run from within the VC++ IDE won't see these unless you run MSDev.Exe from within a command window that you've set up already or you do these settings in your control panel! Also keep in mind that each process can be given different versions of any of these settings or they can all see the same stuff. Its up to you and how you want to use them. And, if you write a custom logger, it can choose to ignore these standard mechanism and log wherever it wants and use any cross process synchronizaton mechanism it wants to. This is just to get you started.
You can create such a 'psuedo release' yourself in the meantime for convenience, but you cannot redistribute this version of the system (except to pass on the original Zip file to others who might be interested.) For that reason, I did not bother with creating one myself. One reason you might want to do this is so that you can create your own project workspaces and just use CIDLib like you would any other third party code (and would the eventual GA release.) In such a situation, you would probably want to have all of the binaries and headers in some common directory (as it will be in the eventual GA distribution release.)
Before you build, you might want to make a couple of changes to the project settings. It is assumed here that you understand the project system of VC++ 5.0, so I don't go into any explicit details here.
Ok, having said all of that, you can build the system now. You need to use the "File - Open Workspace" menu command, and change to the \CID_Dev\Source\AllProjects directory. There you will find the AllProjects workspace file. Just open that file and you will get a listing of all of the projects in the workspace. Select the Debug configuration for the initial exploration, which will probably be selected by default anyway but check. Once opened, you might want to go ahead and make the project settings changes discussed above. They would really only apply to the Debug configuration.
Now just make the AllProjects project the active project, which should be the first project in the list. Then do a build command on the AllProjects project. This will build the whole system. This will take a little while, and even longer if you enabled browser information. When its done, go back and scan the output for any errors. You will get two errors at the very end, for the AllProjects project itself, since it is just a pseudo project that holds other projects. Because of the way that VC++ is set up, this kind of project causes some bogus errors to come out.
If anything goes awry and you cannot figure it out, drop me a line. My e-mail address is on the main home page.
I have not tried building CIDLib on any non-Intel platforms, though it should work as far as I know. When the CIDLib code sees that its not being built on Intel, it replaces any assembly code with equivilent C++ code. So, if you have a non-Intel NT machine, please try it out and let me know if there are any changes I can make to make this process easier. There might be endian'ness issues, which CIDLib is set up to deal with but which I may have overlooked because I don't have a non- Intel system to practice on.
The program that does the documentation compilation is itself written in CIDLib, so it is a non-trivial demo program as well as a utility program. In order to run it and compile the documentation, you need to provide it with the path to the intermediary format source and the output file where you want the files to be compiled to. The source code, in the distribution that you get, is in the \CID_Dev\Source\ClassDocs directory. So, assuming you wanted to output it to the \CIDClassDocs directory, you would use this command:
MakeDocs \CID_Dev\Source\ClassDocs \CIDClassDocs* This assumes that you have built the system as described above. The MakeDocs program is one of the demo/utility programs that is built along with the system.
If the target does not exist, you will be questioned as to whether you really want to output there and create the directory. If you agree, it will create this new directory and compile the files to there. All of the files are put into a single directory, since that makes it much simpler to upload to the web site. Once it is done, open the index.html file in your browser and you are on your way.
Like the rest of CIDLib, the class and member documentation output files use long file names, so you need to build to an NTFS drive. In some cases they use quite long file names but that's ok since you only access them by clicking around in the browser anyway
Just select a demo program as the active project and start debugging into it. All of them are commented pretty profusely so read them carefully and debug into code if you want to see what's going on. You have all of the CIDLib code so you can debug into anything want. The demos are also discussed in the offline documentation.