From 57e98a636587fa8c7af9e85ce062d2978b22d3b4 Mon Sep 17 00:00:00 2001
From: Tinny Ng <tng@apache.org>
Date: Fri, 8 Nov 2002 15:55:56 +0000
Subject: [PATCH] Documentation update: move porting guideline to programming
guide.
git-svn-id: https://svn.apache.org/repos/asf/xerces/c/trunk@174338 13f79535-47bb-0310-9956-ffa450edef68
---
doc/build-misc.xml | 87 +-------------------------------------
doc/faq-distrib.xml | 2 +-
doc/program-others.xml | 95 ++++++++++++++++++++++++++++++++++++++++++
doc/program.xml | 1 +
4 files changed, 99 insertions(+), 86 deletions(-)
diff --git a/doc/build-misc.xml b/doc/build-misc.xml
index 24efe295e..3adde571d 100644
--- a/doc/build-misc.xml
+++ b/doc/build-misc.xml
@@ -201,91 +201,8 @@ perl packageBinaries.pl -s $HOME/&XercesCSrcInstallDir; -o $HOME/temp/&XercesCIn
<s2 title="I wish to port &XercesCProjectName; to my favourite platform. Do you have any suggestions?">
<p>All platform dependent code in &XercesCProjectName; has been
isolated to a couple of files, which should ease the porting
- effort. Here are the basic steps that should be followed to
- port &XercesCProjectName;.</p>
-
- <ol>
-
- <li>The directory <code>src/xercesc/util/Platforms</code> contains the
- platform sensitive files while <code>src/xercesc/util/Compilers</code> contains
- all development environment sensitive files. Each operating
- system has a file of its own and each development environment
- has another one of its own too.
-
- <br/>
-
- As an example, the Win32 platform as a <code>Win32Defs.hpp</code> file
- and the Visual C++ environment has a <code>VCPPDefs.hpp</code> file.
- These files set up certain define tokens, typedefs,
- constants, etc... that will drive the rest of the code to
- do the right thing for that platform and development
- environment. AIX/CSet have their own <code>AIXDefs.hpp</code> and
- <code>CSetDefs.hpp</code> files, and so on. You should create new
- versions of these files for your platform and environment
- and follow the comments in them to set up your own.
- Probably the comments in the Win32 and Visual C++ will be
- the best to follow, since that is where the main
- development is done.</li>
-
- <li>Next, edit the file <code>XercesDefs.hpp</code>, which is where all
- of the fundamental stuff comes into the system. You will
- see conditional sections in there where the above
- per-platform and per-environment headers are brought in.
- Add the new ones for your platform under the appropriate
- conditionals.</li>
-
- <li>Now edit <code>AutoSense.hpp</code>. Here we set canonical &XercesCProjectName;
- internal <code>#define</code> tokens which indicate the platform and
- compiler. These definitions are based on known platform
- and compiler defines.
- <br/>
- <code>AutoSense.hpp</code> is included in <code>XercesDefs.hpp</code> and the
- canonical platform and compiler settings thus defined will
- make the particular platform and compiler headers to be
- the included at compilation.
- <br/>
- It might be a little tricky to decipher this file so be
- careful. If you are using say another compiler on Win32,
- probably it will use similar tokens so that the platform
- will get picked up already using what is already there.</li>
-
- <li>Once this is done, you will then need to implement a
- version of the <ref>platform utilities</ref> for your platform.
- Each operating system has a file which implements some
- methods of the XMLPlatformUtils class, specific to that
- operating system. These are not terribly complex, so it
- should not be a lot of work. The Win32 version is called
- <code>Win32PlatformUtils.cpp</code>, the AIX version is
- <code>AIXPlatformUtils.cpp</code> and so on. Create one for your
- platform, with the correct name, and empty out all of the
- implementation so that just the empty shells of the
- methods are there (with dummy returns where needed to make
- the compiler happy.) Once you've done that, you can start
- to get it to build without any real implementation.</li>
-
- <li>Once you have the system building, then start
- implementing your own platform utilities methods. Follow
- the comments in the Win32 version as to what they do, the
- comments will be improved in subsequent versions, but they
- should be fairly obvious now. Once you have these
- implementations done, you should be able to start
- debugging the system using the demo programs.</li>
- </ol>
-
- <p>Other concerns are:</p>
-
- <ul>
- <li>Does ICU compile on your platform? If not, then you'll need to
- create a transcoder implementation that uses your local transcoding
- services. The Iconv transcoder should work for you, though perhaps
- with some modifications.</li>
- <li>What message loader will you use? To get started, you can use the
- "in memory" one, which is very simple and easy. Then, once you get
- going, you may want to adapt the message catalog message loader, or
- write one of your own that uses local services.</li>
- </ul>
-
- <p>That is the work required in a nutshell!</p>
+ effort. Please refer to <jump href="program-others.html#PortingGuidelines">Porting
+ Guidelines</jump> for further details.</p>
</s2>
diff --git a/doc/faq-distrib.xml b/doc/faq-distrib.xml
index 0298c7a95..5e41abde6 100644
--- a/doc/faq-distrib.xml
+++ b/doc/faq-distrib.xml
@@ -211,7 +211,7 @@ Example: perl packageBinaries.pl -s$HOME/&XercesCSrcInstallDir;
many platforms as there are. Again, due to limited resources
we cannot do all the ports. We will help you make this port
happen. Here are some <jump
- href="build-misc.html#faq-4">Porting
+ href="program-others.html#PortingGuidelines">Porting
Guidelines</jump>.</p>
<p>We strongly encourage you to submit the changes that
diff --git a/doc/program-others.xml b/doc/program-others.xml
index 57b564b62..40c39b4af 100644
--- a/doc/program-others.xml
+++ b/doc/program-others.xml
@@ -273,6 +273,101 @@ parser->parse(xmlFile2);
</s2>
+ <anchor name="PortingGuidelines"/>
+ <s2 title="Porting Guidelines">
+
+ <p>All platform dependent code in &XercesCProjectName; has been
+ isolated to a couple of files, which should ease the porting
+ effort. Here are the basic steps that should be followed to
+ port &XercesCProjectName;.</p>
+
+ <ol>
+
+ <li>The directory <code>src/xercesc/util/Platforms</code> contains the
+ platform sensitive files while <code>src/xercesc/util/Compilers</code> contains
+ all development environment sensitive files. Each operating
+ system has a file of its own and each development environment
+ has another one of its own too.
+
+ <br/>
+
+ As an example, the Win32 platform as a <code>Win32Defs.hpp</code> file
+ and the Visual C++ environment has a <code>VCPPDefs.hpp</code> file.
+ These files set up certain define tokens, typedefs,
+ constants, etc... that will drive the rest of the code to
+ do the right thing for that platform and development
+ environment. AIX/CSet have their own <code>AIXDefs.hpp</code> and
+ <code>CSetDefs.hpp</code> files, and so on. You should create new
+ versions of these files for your platform and environment
+ and follow the comments in them to set up your own.
+ Probably the comments in the Win32 and Visual C++ will be
+ the best to follow, since that is where the main
+ development is done.</li>
+
+ <li>Next, edit the file <code>XercesDefs.hpp</code>, which is where all
+ of the fundamental stuff comes into the system. You will
+ see conditional sections in there where the above
+ per-platform and per-environment headers are brought in.
+ Add the new ones for your platform under the appropriate
+ conditionals.</li>
+
+ <li>Now edit <code>AutoSense.hpp</code>. Here we set canonical &XercesCProjectName;
+ internal <code>#define</code> tokens which indicate the platform and
+ compiler. These definitions are based on known platform
+ and compiler defines.
+ <br/>
+ <code>AutoSense.hpp</code> is included in <code>XercesDefs.hpp</code> and the
+ canonical platform and compiler settings thus defined will
+ make the particular platform and compiler headers to be
+ the included at compilation.
+ <br/>
+ It might be a little tricky to decipher this file so be
+ careful. If you are using say another compiler on Win32,
+ probably it will use similar tokens so that the platform
+ will get picked up already using what is already there.</li>
+
+ <li>Once this is done, you will then need to implement a
+ version of the <ref>platform utilities</ref> for your platform.
+ Each operating system has a file which implements some
+ methods of the XMLPlatformUtils class, specific to that
+ operating system. These are not terribly complex, so it
+ should not be a lot of work. The Win32 version is called
+ <code>Win32PlatformUtils.cpp</code>, the AIX version is
+ <code>AIXPlatformUtils.cpp</code> and so on. Create one for your
+ platform, with the correct name, and empty out all of the
+ implementation so that just the empty shells of the
+ methods are there (with dummy returns where needed to make
+ the compiler happy.) Once you've done that, you can start
+ to get it to build without any real implementation.</li>
+
+ <li>Once you have the system building, then start
+ implementing your own platform utilities methods. Follow
+ the comments in the Win32 version as to what they do, the
+ comments will be improved in subsequent versions, but they
+ should be fairly obvious now. Once you have these
+ implementations done, you should be able to start
+ debugging the system using the demo programs.</li>
+ </ol>
+
+ <p>Other concerns are:</p>
+
+ <ul>
+ <li>Does ICU compile on your platform? If not, then you'll need to
+ create a transcoder implementation that uses your local transcoding
+ services. The Iconv transcoder should work for you, though perhaps
+ with some modifications.</li>
+ <li>What message loader will you use? To get started, you can use the
+ "in memory" one, which is very simple and easy. Then, once you get
+ going, you may want to adapt the message catalog message loader, or
+ write one of your own that uses local services.</li>
+ <li>What should I define XMLCh to be? Please refer to <jump
+ href="build-misc.html#XMLChInfo">What should I define XMLCh to be?</jump> for
+ further details.</li>
+ </ul>
+
+ <p>That is the work required in a nutshell!</p>
+ </s2>
+
<anchor name="CPPNamespace"/>
<s2 title="Using C++ Namespace">
diff --git a/doc/program.xml b/doc/program.xml
index 9c2519290..d1f57068e 100644
--- a/doc/program.xml
+++ b/doc/program.xml
@@ -78,6 +78,7 @@
<li><jump href="program-others.html#GrammarCache">Preparsing Grammar and Grammar Caching</jump></li>
<li><jump href="program-others.html#LoadableMessageText">Loadable Message Text</jump></li>
<li><jump href="program-others.html#PluggableTranscoders">Pluggable Transcoders</jump></li>
+ <li><jump href="program-others.html#PortingGuidelines">Porting Guidelines</jump></li>
<li><jump href="program-others.html#CPPNamespace">Using C++ Namespace</jump></li>
</ul>
</s2>
--
GitLab