CIDLib Version 0.500 Quick Start Info

Quick Start

This document is for those who need immediate gratification and want to just get going. Eventually you should read through the offline documentation, but this will get you started and set up and ready to play with the demo programs. Just by debugging through the demo programs you will pick up a lot of what CIDLib is about and what it can do.

All of this stuff is covered in much more detail in the offline documentation.

First of all, what you need at a minimum:

All of this stuff needs to be installed and setup correctly and in working order. If you've got that taken care of, then the next step is to install the CIDLib system.

Installing the CIDLib System

Once you've downloaded the Zip file (see the main home page for download instructions), you need to unzip it to build the CIDLib development tree. Be sure that you are in the root directory of the drive you want to install it on, because the Zip file will recreate the \CID_Dev directory and all of its subdirectories and it must be under the root in order for the build environment to work correctly.

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:

Setting up the Environment

CIDLib does not need much environmental setup itself, but to get the most out of it you need to do a bit. If you want to do the quick version, then you can just run the \CID_Dev\Source\Cmd\SetCIDEnv.Cmd command file. However, it assumes that you have set the CIDDRIVE environment variable to the drive that you installed the CIDLib system onto. So either edit the file and add a SET CIDDRIVE=X: statement or set CIDDRIVE in your environment before running it. What I do is set CIDDRIVE in my control panel as the only setting that is global. Then I run SetCIDEnv.Cmd in the command windows I want to work in. I then start MSDev from that command window so that programs run from within VC++ will see these settings. But, you can also put all these settings in your global environment via the control panel.

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.

Building the System

In order to massively reduce distribution size of these beta releases, you get to build the CIDLib system yourself, i.e. it does not come prebuilt. Its very easy to do, and will probably take you less time that you would have spent downloading a prebuilt version. Since only developers will use these beta versions, this makes a lot of sense since you can just work within the same development environment that I do. This is to allow you to learn it quickly and explore the demo programs all within a single workspace. The eventual GA version will also come with a 'distribution' form which will just contain the Lib, DLL, and Hpp files.

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.

CIDLib supports the usual Debug and Release configurations that VC++ uses by default. However, it does not use the (dumb in my opinion) default convention of putting output files in subdirectories under the source. Instead, the Debug build outputs to \CID_Dev\DevResult and the Release build outputs to \CID_Dev\ProdResult. Each project's temporary files go to a subdirectory under the result directory, which has the same name as the project. Their output files go to the main result directory. So, once built, all the binary files that you would need are in these main result directories, so you only need to add them to your path.

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.

Building the Class and Member Docs

The class and member documentation is on my web site so you can access it from there if you are online. If you want to have your own local version, then you will need to download the files from the web site, or you can just 'build' it for yourself. The class and member docs are written in an intermediary form that can (theoretically though I've not done it yet) be compiled into a number of output formats.

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

Exploring the Demos

If the build went correctly and you've got the environment set up, then you can start playing with the demo programs. The demo programs are set up by categories, so that its obvious what they demonstrate. Of course all of them tend to demonstrate fundamental services used by most programs, but they do have a particular orientation towards certain functionality.

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.

So Have At It

That's it. You should be up and running at this point. If you have any problems, contact me and I'll be glad to help. You can start playing with the demo programs or browsing the code. You will probably want to get into the offline documentation before you attempt any serious work, or if you have big picture questions.