home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / xwphescr.zip / XWPH0208.ZIP / readme.txt < prev    next >
Text File  |  2002-02-03  |  9KB  |  232 lines
  1. XWP Helpers 0.9.7 README
  2. (W) Ulrich Möller, October 26, 2000
  3. Last updated Feb 03, 2002 Ulrich Möller
  4.  
  5.  
  6. 0. CONTENTS OF THIS FILE
  7. ========================
  8.  
  9.     1. LICENSE, COPYRIGHT, DISCLAIMER
  10.     2. INTRODUCTION
  11.     3. EXECUTABLE TOOLS
  12.     4. CREATING CODE DOCUMENTATION
  13.     5. COMPILING
  14.     6. INCLUDING HEADER FILES
  15.  
  16.  
  17. 1. LICENSE, COPYRIGHT, DISCLAIMER
  18. =================================
  19.  
  20.     Copyright (C) 1997-2001 Ulrich Möller,
  21.                             Christian Langanke,
  22.                             and others (see the individual source files).
  23.  
  24.     Most of this library is published under the GNU General Public Licence.
  25.     You can redistribute it and/or modify those parts under the terms of the
  26.     GNU General Public License as contained in the file COPYING in the
  27.     main directory.
  28.  
  29.     Parts of this library are published under MIT licence. See the
  30.     COPYING.MIT file in the main directory.
  31.  
  32.     See the individual source files for what licence applies.
  33.  
  34.     This program is distributed in the hope that it will be useful,
  35.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  36.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  37.  
  38.  
  39. 2. INTRODUCTION
  40. ===============
  41.  
  42.     Welcome to the XWorkplace Helpers.
  43.  
  44.     This CVS archive is intended to support OS/2 developers with any
  45.     code they might need writing OS/2 programs.
  46.  
  47.     The XWPHelpers are presently used in XWorkplace and WarpIN. They
  48.     started out from various code snippets I created for XFolder,
  49.     the predecessor of XWorkplace. I then isolated the code which could
  50.     be used independently and put that code into separate directories
  51.     in the WarpIN CVS repository (also at Netlabs).
  52.  
  53.     At Warpstock Europe 2000 in Karlsruhe, I talked to a number of
  54.     developers and then decided that this should become an independent
  55.     Netlabs CVS archive so that other people can more easily contribute.
  56.  
  57.     Even though the helpers are called "XWorkplace helpers", they
  58.     have nothing to do with WPS and SOM programming. They can help
  59.     any OS/2 programmer.
  60.  
  61.     The XWPHelpers offer you frequently used code for writing all
  62.     sorts of OS/2 programs, including:
  63.  
  64.     --  standard C code which is independent of the OS/2 platform
  65.         (and should even work for Unix or Windows);
  66.  
  67.     --  OS/2-specific code which can be used in any OS/2 program
  68.         (VIO or PM);
  69.  
  70.     --  PM-specific code which assists you in writing PM programs.
  71.  
  72.     The XWPHelpers can be compiled with EMX/GCC or IBM VisualAge
  73.     C++ 3.08. They can be used with C or C++ programs. All typecasts
  74.     should be C++-compatible.
  75.  
  76.  
  77.     Getting Sources from Netlabs CVS
  78.     --------------------------------
  79.  
  80.     First set the CVS enviroment:
  81.         CVSROOT=:pserver:guest@www.netlabs.org:d:/netlabs.src/xwphelpers
  82.         USER=guest
  83.  
  84.     Then, to check out the most current XWPHelpers sources, create
  85.     a subdirectory in your CVS root dir called "xwphelpers".
  86.  
  87.     Do a "cvs login" with "readonly" as your password and do a
  88.     "cvs checkout ." from the "xwphelpers" subdirectory. Don't forget
  89.     the dot.
  90.  
  91.     Alternatively, use the Netlabs Open Source Archive Client (NOSAC).
  92.     See http://www.netlabs.org/nosa for details.
  93.  
  94.     In any case, I strongly recommend to create a file in $(HOME)
  95.     called ".cvsrc" and add "cvs -z9" in there to enable maximum
  96.     compression during transfers. This greatly speeds up things.
  97.  
  98.  
  99. 3. EXECUTABLE TOOLS
  100. ===================
  101.  
  102.     The root directory of this repository contains a few executables
  103.     in binary form that are used by XWorkplace and WarpIN.
  104.  
  105.  
  106.     --  FastDep.exe was written by Knut Stange Osmundsen (taken from
  107.         the Odin sources) and is used by the "nmake dep" facility
  108.         of both WarpIN and XWorkplace. This scans C source files
  109.         and writes dependencies for the makefiles automatically.
  110.  
  111.     --  h2i.exe was written by me (the sources are in the xwphelpers
  112.         repository, in the "tools" directory) to translate a bunch
  113.         of HTML files to IPF.
  114.  
  115.     --  strrpl.exe was written by me (the sources are in the warpin
  116.         repository, in the "tools" directory) to replace strings in
  117.         text files.
  118.  
  119.     --  xdoc.exe was written by me (the sources are in the warpin
  120.         repository, in the "tools" directory) to extract documentation
  121.         from C source files directory. See "Creating code documentation"
  122.         below.
  123.  
  124.  
  125. 4. CREATING CODE DOCUMENTATION
  126. ==============================
  127.  
  128.     The XWPHelpers do not come with pre-made documentation. However,
  129.     you can automatically have extensive, categorized documentation
  130.     generated automatically from the C sources using my "xdoc"
  131.     utility, which resides in the main directory of the helpers.
  132.     (The source code for xdoc is in the WarpIN CVS repository
  133.     because it shares some C++ code with WarpIN.)
  134.  
  135.     To have the code generated, simply call "createdoc.cmd" in the
  136.     main directory. This will call xdoc in turn with the proper
  137.     parameters and create a new "HTML" directory, from where you
  138.     should start with the "index.html" file.
  139.  
  140.  
  141. 5. COMPILING
  142. ============
  143.  
  144.     You don't have to worry about compilation if you only want
  145.     to compile XWorkplace or WarpIN. The makefiles of those two
  146.     projects are set up properly to automatically compile the
  147.     XWPHelpers as well. This section is only for people who
  148.     want to compile the XWPHelpers separately for use in a
  149.     different project.
  150.  
  151.     Compiling is a bit tricky because the code and the makefiles
  152.     were designed to be independent of any single project. As a
  153.     result, I had to used environment variables in order to pass
  154.     parameters to the makefiles.
  155.  
  156.     The most important environment variable is PROJECT_BASE_DIR.
  157.     This should point to the root directory of your own project.
  158.     In this directory, src\helpers\makefile expects a file called
  159.     "setup.in" which sets up more environment variables. You can
  160.     take the one from the XWPHelpers makefile as a template.
  161.  
  162.     Here's an example: Say you have a CVS root directory of
  163.     "C:\cvs" on your system. The XWPHelpers reside in
  164.     "C:\cvs\xwphelpers". Your own project resides in
  165.     "C:\cvs\myproject" (plus subdirectories). So set
  166.     PROJECT_BASE_DIR to "C:\cvs\myproject" and put setup.in
  167.     in that directory.
  168.  
  169.     Note that the XWPHelpers also expect a "setup.h" header
  170.     file to be somewhere on your INCLUDE path. See remarks
  171.     below.
  172.  
  173.     See the top of src\helpers\makefile for additional variables.
  174.  
  175.     Of course, nothing stops you from writing your own makefile
  176.     if you find all this too complicated. However, if you choose
  177.     to use my makefile from within your own project, you can
  178.     then simply change to the src\helpers directory and start a
  179.     second nmake from your own makefile like this:
  180.  
  181.         @cd xxx\src\helpers
  182.         nmake -nologo "PROJECT_BASE_DIR=C:\myproject" "MAINMAKERUNNING=YES"
  183.         @cd olddir
  184.  
  185.  
  186. 6. INCLUDING HEADER FILES
  187. =========================
  188.  
  189.     The "include policy" of the helpers is that the "include"
  190.     directory in the helpers source tree should be part of your
  191.     include path. This way you can include helper headers in
  192.     your own project code using
  193.  
  194.         #include "helpers\header.h"
  195.  
  196.     so that the helpers headers won't interfere with your own
  197.     headers.
  198.  
  199.     Note that all the helpers C code includes their own include
  200.     files this way. As a result, the XWPHelpers "include"
  201.     directory must be in your include path, or this won't
  202.     compile.
  203.  
  204.     I have a "flat" include policy, meaning that include files
  205.     may not include other files. Instead, #include's may only
  206.     occur in C files. This makes makefile dependencies easier
  207.     to maintain.
  208.  
  209.     Besides, the helpers C code expects a file called "setup.h"
  210.     in your include path somewhere. This is included by _all_
  211.     the C files so you can (re)define certain macros there.
  212.     XWorkplace and WarpIN both have such a header file in their
  213.     respective "include" directories.
  214.  
  215.     With V0.9.7, many function prototypes have been changed in
  216.     the helpers headers to allow exporting them in a DLL.
  217.     (This was necessary for creating XWorkplace plugin DLLs.)
  218.     As a result, you now MUST define XWPENTRY in your setup.h
  219.     to contain the linkage for the helpers functions. This
  220.     can look like this:
  221.  
  222.         #ifdef __EMX__
  223.             // with EMX, do nothing; EMX always uses _System linkage
  224.             #define XWPENTRY
  225.         #elif defined (__IBMCPP__) || defined (__IBMC__)
  226.             // with VAC, use _Optlink; that's faster than _System
  227.             #define XWPENTRY _Optlink
  228.             // or: #define XWPENTRY _System
  229.         #endif
  230.  
  231.  
  232.