source: trunk/readme.txt@ 120

Last change on this file since 120 was 85, checked in by umoeller, 24 years ago

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