Compiling XWP

''Please note that this is not the "official" how-to, but just a collection of suggestions an tips harvested from progref.inf file included in the XWP's sources, from Ulrich's page about setting up CVS and from the XWP mailing lists. The "official" how-to remains the progref.inf file included in the XWP's sources. Special thanks to Steven Levine for reviewing, correcting and enhancing the text''

Getting sources from CVS
To compile XWP you need to retrieve both the XWP Sources and XWP Helpers from the Netlabs' CVS server.

Supposing that you already have a working CVS setup, do this:

1) Create the CVS root folder (e.g. x:\CVS) and then do:

SET CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/xworkplace

This is the location of the XWP Sources repository at Netlabs.

2) Create a subdirectory in your CVS root directory named "xworkplace" (e.g. x:\cvs\xworkplace), change to this subdirectory.

3) If this is first time you have used the XWP Sources respository, you need to log in. Do:

SET USER=guest CVS login

and enter "readonly" when you are prompted for password. Cvs remembers your login information in %HOME%\.cvspass, so you only need to login if this information is not already recorded for this repository.

4) Do:

cvs checkout -r branch-1-0.

Don't forget the last dot! This command will retrieve the most recent XWP sources from the CVS repository for the XWP 1.x branch into the current subdirectory. Cvs calls subdirectory tree and its contents a sandbox. More on branches and tags below.

Now you need to retrieve the XWP helpers:

1) First, do:

SET CVSROOT=:pserver:guest@www.netlabs.org:/netlabs.cvs/xwphelpers

This is the location of the XWP Helpers repository.

2) Create a subdirectory in your CVS root directory named "xwphelpers" (e.g. x:\cvs\xwphelpers), change to this subdirectory.

3) If this is first time you have used the XWP Sources respository, you need to log in. Do:

SET USER=guest CVS login

and enter "readonly" when you are prompted for password. Cvs remembers your login information in %HOME%\.cvspass, so you only need to login if this information is not already recorded.

4) Do:

cvs checkout -r branch-1-0.

You have now downloaded all the files you need to compile the latest XWP branch stuff.

Branch, trunk, tags...
As you sooner or later will like to play with the trunk, or compile a specific XWP version, maybe because you are working on translating it, a good idea is to maintain different sandboxes for each version you are working with. This will save you time. A good directory organization could be:


 * Your CVS root folder
 * XWP Sources branch
 * XWP Sources trunk
 * XWP Helpers branch
 * XWP Helpers trunk

If disk space is a problem, you can use a single set of sandboxes and switch the sandbox content as needed. More on this below.

To checkout the trunk, checkout with no tag using:

cvs checkout.

in both the XWP Sources and the XWP Helpers sandbox directories.

To checkout the 1.0 branch, use the "branch-1-0" tag:

cvs checkout -r branch-1-0.

in the XWP sources and the XWP helpers sandbox directories.

To checkout version 1.0.7 (the latest released version):

cvs checkout -r pr_0005_1-0-7.

in the XWP sources directory and

cvs checkout -r pr_0016_xwp1-0-7.

in the XWP helpers directory.

Once you have done an initial checkout from CVS, you can use the cvs status -v filename command to determine which tags exist. For example, run:

cvs status -v -l makefile

from the x:\cvs\xworkplace directory to see the existing tags for the XWorkplace package. This works because the developers always tag makefile for every release even if this file has not changed.

All the above samples are for an intiial checkout from the CVS server. This means that you are downloading from CVS into an empty directory.

Once you have done an initial checkout of a branch or the trunk, you usually want to use the "update" command to download files modified by others instead of the "checkout" command. The update command is faster than the checkout command because it generally does a lot less work. Run the command:

cvs upd

in each subdirectory to be updated. It is safe to use this command even if you have changes in progress. Cvs will not overwrite your uncommited changes.

When working with an existing sandbox, there's no need to set CVSROOT or USER. Cvs records this data in control files within the sandbox.

You can switch the content of an existing sandbox to a different release or branch. To switch your sandbox directories to the 1.0.6 release, the commands would be:

cvs upd -A -r pr_0004_1-0-6

in the XWP sources directory and

cvs upd -A -r pr_0015_xwp1-0-6

in the XWP helpers directory.

Tags can be confusing to those new to CVS. There are revision tags and branch tags. They often look the same, but they do not work the same. A revision tag refers to a specific file. A branch tag refers to the newest file on the branch. XWP releases are tagged with revision tags.

If you checkout using a revision tag, you can not commit changes. If you checkout using a branch tag, you can commit changes, if you have permission to do commits. The trunk is effectively an unnamed branch. The XWP naming convention is that branch tags always contain the word branch in the tag name. If you are not sure if a tag is a branch tag or a revision tag, use the cvs status command.

Compiling the beast

 * IBM VisualAge C++ 3.0 with fixpak 8 is recommended (and it is also the only environment currently supported.
 * OS/2 Developer's Toolkit for all the SOM header files and the SOM compiler: the ones included in eCS 1.2 CD #2 seems good. If you are using some other Toolkit, be sure to backlevel emitc.dll to the OS/2 Warp 4.0 Toolkit version.

Now, you have on your computer all what is needed to compile XWP.

1) first of all, adjust x:\CVS\xworkplace\config.in to your needs; 2) then, from x:\CVS\xworkplace\ run

nmake dep

If you have never built XWorkplace before, "nmake dep" will give you lots of warnings that headers could not be found. This is normal.

3) After that, run either "nmake all" or "nmake really_all". "nmake all" will only rebuild XFLDR.DLL, XWPDAEMN.EXE and XWPHOOK.DLL while "nmake really_all" will produce the full set of XWorkplace executables plus the NLS files.

You have good chance to get an error like:

E:\netlabs_CVS\xworkplace\bin\modules\xwphook.dll => E:\programs\xworkplace\binxwphook.dll SYS0032: Process can't access file...

This means that you have XWorkplace running and you have to UNLOCK the files first if you are copying over your running files. Put XWP_UNLOCK_MODULES = YES in CONFIG.IN. It's down near the bottom. The Unlock utility from the LxLite package is required.

Notes for contributors
If you modify something in the source and you want to send the developer the diffs, you can easily create them with CVS with the following command:

cvs -z3 diff -u >description_of_changes.diff

from the root of the sandbox is my preference. gnupatch will accept these without issues. Attach the .diff file in an email and send it to Paul Ratcliffe, the code maintainer.

You should ideally do this for both the branch and the trunk, but currently Paul will take only branch diffs. Often they will be the same anyway.

You need to remember to do the diffs for the XWP Helpers as well if you modify something there.

Notes for translators
As a sample for people interested in translating XWP to their own language, here is explained how the Italian translation of XWP is maintained. The following is the folder structure I use:

\Netlabs_CVS \Netlabs_CVS\xwphelpers \Netlabs_CVS\xworkplace_branch \Netlabs_CVS\xworkplace_105 \Netlabs_CVS\xworkplace_106

(xwphelpers repository doesn't have "sandboxes" as there is nothing inside NLS-related). Taking XWorkplace version 1.0.7 as sample: I copy the \xworkplace_branch directory as \xworkplace_107, then do:

cvs checkout -r branch-1-0. cvs update -j pr_0005_1-0-7

in \xworkplace_107 and

cvs checkout -r branch-1-0. cvs update -j pr_0016_xwp1-0-7

in the XWP helpers directory. Since you can not commit changes if you have checked out a release, it is necessary to checkout the branch and then backout any changes that were made since the version was released.

I can now compare (with ddiff and kdiff) \xworkplace_107\001 directory with the content of \xworkplace_branch\001, and update \xworkplace_107\039 as needed. Once everything has been updated and tested, I commit my changes with

cvs commit

from \xworkplace_107\039 directory and then, from the same directory, create a release tag for the Italian NLS subdirectory tree:

cvs tag ggamba_0003-1-0-7

If I need to make some additional updates, this tag allows me to recreate the sandbox.

Finally, after editing the config.in file in the appropriate way, I compile the translated resource with the command:

nmake nls

In addition, "nmake wpi_nls" will create the archive in the release directory.