View source for 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 [http://www.xworkplace.org/cvs.html 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.''

----

== Getting sources from CVS ==

To compile XWP you need to retrieve from Netlabs' CVS server both XWP and XWP helpers sources.

Supposing that you already have a [http://www.xworkplace.org/cvs.html 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

2) create a subdirectory in your CVS root directory named "xworkplace" (e.g. x:\cvs\xworkplace), change to it and do:

     SET USER=guest

3) from the same directory, do:

     CVS login

and enter "readonly" when you are prompted for password;

4) do:

     cvs checkout -r '''branch-1-0''' .

Don't forget the last dot! This last command will retrieve the most updated stuff from CVS.

Now you need to retrieve the XWorkplace helpers:

1) go again in your CVS root folder (e.g. x:\CVS) and do:

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

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

     cvs checkout -r '''branch-1-0''' .

You just downloaded from CVS all what you need to compile the latest XWP branch stuff!

===Branch, trunk, tags...===

As you sooner or later will like to play with trunk, or to compile a specific XWP version, maybe because you are working on translating it, a good idea is to maintain different ''sandboxes'' for trunk and branches. A good directory organization could be:

*your CVS root folder 
** XWP branch
** XWP trunk
** XWP Helpers branch
** XWP Helpers trunk

To checkout the '''trunk''', use no tag:

     cvs checkout .

both for xwp and xwp helpers.

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

     cvs checkout -r branch-1-0 .

again both for xwp and xwp helpers. To checkout '''version 1.0.6''' (latest released version):

     cvs checkout -r pr_0004_1-0-6

in xworkplace directory and 

     cvs checkout -r pr_0015_xwp1-0-6

in the xwphelpers one. Once the first checkout from CVS is done, the ''cvs status -v filename'' command will tell you which tag exist; for example, running:

     cvs status -v makefile 

from the x:\cvs\xworkplace directory will tell you which are the existing tags for the XWorkplace package.

All the above samples are to checkout from the CVS server, that means that you are importing from CVS from scratch, in an empty directory. 

Since you have done a checkout, you can use the "update" command instead that the "checkout" one. The last sample would become:

     cvs upd -A -rpr_0004_1-0-6

and

     cvs upd -A -rpr_0015_xwp1-0-6

== 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.

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 change 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 branch only diffs. Often they will be the same anyway.

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


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

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

(I don't need different "sandboxes" of xwphelpers repository). I routinely update the branch. When version xyz of XWP is released, I copy the \xworkplace_branch directory as \xworkplace_xyz, then do:

     cd \xwp_work
     set R=:pserver:guest@www.netlabs.org:/netlabs.cvs/xworkplace
     cvs -d %R% checkout -r pr_0002-1-0-4 .
     cd 039
     cvs update -A -r branch-1-0

In this way I checkout XWP sources using the release tag while keeping Italian NLS subdirectory tree at branch level.

I then compare (with ddiff and gfc) \xworkplace_xyz\001 directory with content of \xworkplace_branch\001, and update \xworkplace_xyz\039 as needed. Once everything has been updated and tested, I commit my changes with 

     cvs commit

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

     cvs tag ggamba_0002-1-0-6

If I need to make some follow on updates, this tag allow me to recreate the sandbox.

Finally, after editing config.in file in the appropriate way, with the command:

     nmake nls

I compile the translated resources. In addition, "nmake wpi_nls" will create the archive in the release directory.