gecko-dev/xpcom/doc/xpcom-standalone.html
dp%netscape.com 41a3177737 More caveats.
2000-05-26 01:22:01 +00:00

170 lines
4.6 KiB
HTML

<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Suresh Duddi">
<meta name="GENERATOR" content="Mozilla/4.71 [en] (X11; U; Linux 2.2.12-20 i686) [Netscape]">
</head>
<body>
<center>
<h2>
Standalone XPCOM v 0.5</h2></center>
<center>Version 0.5
<br>15 May 2000
<br>Suresh Duddi &lt;dp@netscape.com>
<hr WIDTH="100%"></center>
<h3>
1.0&nbsp; Overview</h3>
Standalone XPCOM is a tree configuration, that when built, provides a minimal
set of libraries (shared mostly) that can be used to get all features of
XPCOM. The contents of this standalone XPCOM in general are:
<ul>
<li>
NSPR : mozilla/nsprpub</li>
<li>
Registry : mozilla/modules/libreg</li>
<li>
XPCOM : mozilla/xpcom</li>
</ul>
<b>NOTE 1: xpcom apis are not frozen yet. By XPCOM 1.0 release they will
be.</b>
<br><b>NOTE 2: xpcom standalone differs from the xpcom built with mozilla.
Hence cannot be used with the mozilla browser.</b>
<h3>
2.0&nbsp; Building Standalone XPCOM</h3>
Here are the instructions for building the Standalone XPCOM on unix:
<br>&nbsp;
<ol><b>Step 1 : Pull the sources</b>
<li>
<tt>cvs -z 3 co mozilla/client.mk</tt></li>
<li>
<tt>cd mozilla</tt></li>
<li>
<tt>gmake -f client.mk pull_all BUILD_MODULES=xpcom</tt></li>
</ol>
<ol><b>Step 2 : Build XPCOM Standalone (unix)</b>
<li>
<tt>configure --enable-modules=xpcom</tt></li>
<li>
<tt>gmake</tt></li>
</ol>
<i>Thanks to Christopher Seawood &lt;cls@seawood.org> for make this so
simple.</i>
<h3>
3.0&nbsp; Testing Standalone XPCOM</h3>
<tt>xpcom/sample</tt> contains a sample application and a component. This
should get built by default.
<ul>
<li>
<tt>nsTestSample</tt> is the sample application. This should have been
installed in your <tt>bin/</tt> directory.</li>
<li>
<tt>libsample.so (unix) </tt>is the sample component implementation that
the sample application will try to instantiate. This should have been installed
in your <tt>bin/components</tt> directory</li>
</ul>
To run the test,
<ol>
<li>
cd to your <tt>bin/</tt> directory</li>
<li>
setenv LD_LIBRARY_PATH .</li>
<li>
<tt>./nsTestSample</tt></li>
<br><tt>Warning: MOZILLA_FIVE_HOME not set.</tt>
<br><tt>nsNativeComponentLoader: autoregistering begins.</tt>
<br><tt>nsNativeComponentLoader: autoregistering succeeded</tt>
<br><tt>Inital print: initial value</tt>
<br><tt>Set value to: XPCOM defies gravity</tt>
<br><tt>Final print : XPCOM defies gravity</tt>
<br><b><tt>Test passed.</tt></b></ol>
<h3>
4.0&nbsp; Test FAILED: What went wrong ?</h3>
The most common case of why the sample would have failed if you didn't
run it from the bin directory. Here are some error messsages and possible
ways of fixing them.
<ol>
<li>
<b><tt>./nsTestSample: error in loading shared libraries: libxpcom.so:
cannot open shared object file: No such file or directory</tt></b></li>
<ol>LD_LIBRARY_PATH not set. To fix "<tt>setenv LD_LIBRARY_PATH ."</tt></ol>
<li>
<b>Link errors when building xpcom standalone</b></li>
<ol>This is mostly due to the fact that probably xpcom is not being built
standalone. Make sure you did "<tt>configure --enable-modules=xpcom"</tt></ol>
</ol>
<h3>
5.0&nbsp; Whats the difference between Standalone and non-Standalone XPCOM</h3>
Here is what we had to do to get a working standalone XPCOM
<ol>
<li>
Disabled all forms of unicode conversion. nsString, nsCRT were using this
in various forms. Only ASCII is expected to work. Other charsets including
unicode are not guaranteed to work.</li>
<li>
Disabled nsUnicharInputStream. This causes nsPersistentProperties to always
fail.</li>
<li>
Disabled control of XPT from preferences.</li>
<li>
Disabled use of ZIP format of XPT files.</li>
</ol>
Until we fix these differences, the non-standalone xpcom will be the one
used by the mozilla browser.
<h3>
6.0&nbsp; TODO for v 1.0</h3>
<ol>
<li>
Enable XPCOM to work with unicode. Unicode, ASCII and ISO8859-1 will be
the charset that will be self supported by XPCOM.</li>
<li>
Optional exclusion of specific features into standalone XPCOM like unicode
support, registry, xpconnect. Tweeking these options will cause reduction
in memory requirements and size.</li>
<li>
Get <tt>xpcom/tests</tt> directory upto date and documented.</li>
<li>
Make standalone XPCOM the only deliverable from xpcom. No more <tt>#ifndef
XPCOM_STANDALONE</tt></li>
<li>
Update this document for both Windows and Mac.</li>
<li>
API freeze and documentation</li>
</ol>
<h3>
7.0&nbsp; Future (post v 1.0)</h3>
mmh! let me think...
<p>
<hr WIDTH="100%">
<br>Suresh Duddi &lt;dp@netscape.com>
</body>
</html>