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@cvs.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 repository, 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@cvs.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 repository, 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 XWP version 1.0.8 (the latest released version):

    cvs checkout -r pr_0006_1-0-8 .

in the XWP sources 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 initial 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 uncommitted 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). VAC3.65 can be used for multi-threaded widgets and to build a multi-threading helpers36.lib
• 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.
• Several versions of rc.exe are around, and not all of them work well for XWP compilation. Good versions are for sure:

    Version 4.00.001 Jun 27 1996

and

    Version 4.00.010 Apr 26 1999 

which is essentially the same version as the above with some fixes done specifically for the Mozilla team. It was available at:

    ftp://ftp.software.ibm.com/ps/products/warpzilla/os2tk40rc.zip

Finally, someone successfully replaced rc.exe from IBM with the one from the Open Watcom compiler, wrc.exe, that accepts much longer command lines.

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.

In case of problems, verify if x:\CVS\xworkplace\bin\full directory has been created. If not, create it.

You have also good chance to get an error like:

  E:\netlabs_CVS\xworkplace\bin\modules\xwphook.dll => E:\programs\xworkplace\bin\xwphook.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. Check that XWP_UNLOCK_MODULES = YES line exists in CONFIG.IN (it's down near the bottom). The Unlock utility from the LxLite package is required. If XWP_UNLOCK_MODULES should not be enough, manually unlock XWPHOOK.DLL and XWPDAEMN.EXE.

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.