XPCOM Glue

  • Revision slug: XPCOM_Glue
  • Revision title: XPCOM Glue
  • Revision id: 83116
  • Created:
  • Creator: Plasticmillion
  • Is current revision? No
  • Comment 9 words added

Revision Content

The XPCOM Glue is a static library which component developers and embedders can link against. It allows developers to link only against the frozen XPCOM method symbols and maintain compatibility with multiple versions of XPCOM.

Compiling or linking against XPCOM headers

There are three ways to compile/link against XPCOM headers/libraries:

Frozen linkage: dependent glue (dependent on xpcom.dll)

XPCOM modules, i.e. extension or XULRunner application components, should use the dependent glue.

Code which wishes to use only frozen symbols but can tolerate a load-time dependency on xpcom.dll should link against xpcomglue_s.lib and xpcom.lib. It should not link against xpcom_core.lib. This is the case for XPCOM components, because they are loaded into Mozilla which already has full XPCOM loaded and initialized.

Frozen linkage: standalone glue (no DLL dependencies)

Use this when you have a custom application where you want to embed Gecko to show webpages in your own window. I.e. this linkage strategy is used when an embedder needs to bootstrap XPCOM by finding a compatible GRE on disk and loading it.

In order to use XPCOM, the embedding application first needs to find where the XPCOM runtime is located. This is typically done using GRE_GetGREPathWithProperties. Then, the code must call XPCOMGlueStartup, which will dynamically link against the XPCOM runtime. Only then can the embedding application initialize and use XPCOM.

Embedding code which wishes to use only frozen symbols and cannot tolerate a load-time dependency on xpcom.dll should #define XPCOM_GLUE 1 while compiling, and link against xpcomglue.lib. It should not link against xpcomglue_s.lib or xpcom.lib.

Embedders using the standalone glue typically also need to avoid linking against NSPR as well. However, when using threadsafe together with the glue libraries from Gecko 1.8 or later, a special step needs to be taken to use NS_IMPL_THREADSAFE_ISUPPORTSn. This is because it forces a dependency on the NSPR library, which can otherwise be avoided. As described in {{ Bug("299664") }}, the preprocessor symbol XPCOM_GLUE_USE_NSPR needs to be defined.

Using Mozilla internal linkage

Mozilla internal code defines MOZILLA_INTERNAL_API while compiling and links against xpcom.lib and xpcom_core.lib. In almost all cases embedders should *not* use internal linkage. Components using internal linkage will have shared-library dependencies against non-frozen symbols in the XPCOM libraries, and will not work with any other versions of XPCOM other than the one it was compiled against.

Internal linkage will be unavailable to extension authors in XULRunner 1.9 (Firefox 3) because the nonfrozen symbols will not be exported from libxul. Extension and application authors currently using internal linkage should read the guide on Migrating from Internal Linkage to Frozen Linkage.

Sample Compiler/Linker Flags

Code compiled using XPCOM headers should always #include "xpcom-config.h" from the SDK, to ensure that XPCOM #defines are correct.

 

Linking Strategy: Dependent Glue Standalone Glue
Compiler Flags:
Cross-Platform #include "xpcom-config.h" #include "xpcom-config.h"
#define XPCOM_GLUE
Windows /FI "mozilla-config.h"
Linux -include "mozilla-config.h"
Linker Flags:
Windows -LIBPATH:c:/path/to/sdk/lib xpcomglue_s.lib xpcom.lib nspr4.lib -LIBPATH:c:/path/to/sdk/lib xpcomglue.lib
Mac

-L/path/to/sdk/lib -L/path/to/sdk/bin -Wl,-executable-path,/path/to/sdk/bin -lxpcomglue_s -lxpcom -lnspr4

when building against a XulRunner derived SDK, use:
-L/path/to/sdk/lib -L/path/to/xulrunner-bin -Wl,-executable_path,/path/to/xulrunner-bin -lxpcomglue_s -lxpcom -lnspr4
where 'xulrunner-bin' is either /Library/Frameworks/XUL.framework/Versions/Current/ or /path/to/xulrunner-build/{{ mediawiki.external('platform') }}/dist/bin

-L/path/to/sdk/lib -lxpcomglue
Linux

-L/path/to/sdk/lib -L/path/to/sdk/bin -Wl,-rpath-link,/path/to/sdk/bin -lxpcomglue_s -lxpcom -lnspr4

Write it exactly as stated, see Notes.

-L/path/to/sdk/lib -lxpcomglue

Notes

  • Never link against xpcomglue.lib and xpcomglue_s.lib at the same time.
  • Never link against xpcomglue.lib and xpcom.lib at the same time.
  • For XULRunner 1.9, on Linux you should use either the .pc files. For example: pkg-config --cflags --libs libxul.pc
  • These instructions are for Mozilla 1.8 and above. When using a SDK from Mozilla 1.7 or earlier, you must define MOZILLA_STRICT_API when using any form of the glue.
  • Linux and Mac: Make sure the Gecko libraries are listed after your object (.o) files on the link line.
  • Linux and Mac: Write the linker options exactly as stated (just replacing the /path/to/sdk/), otherwise you get an undefined symbol: ...NS_TableDrivenQI...QITableEntry... at runtime (not compile time) (in debug builds) or your module just won't load (in optimized builds).
  • In principle, #include "mozilla-config.h" should also work, if it's the first #include in .cpp, but preprocessor option is how it's usually included.

See Also

 

Revision Source

<p>The XPCOM Glue is a static library which component developers and embedders can link against. It allows developers to link only against the frozen XPCOM method symbols and maintain compatibility with multiple versions of XPCOM.</p>
<h3 name="Compiling_or_linking_against_XPCOM_headers">Compiling or linking against XPCOM headers</h3>
<p>There are three ways to compile/link against XPCOM headers/libraries:</p>
<h4 name="Frozen_linkage:_dependent_glue_.28dependent_on_xpcom.dll.29">Frozen linkage: dependent glue (dependent on xpcom.dll)</h4>
<p>XPCOM modules, i.e. extension or XULRunner application components, should use the dependent glue.</p>
<p>Code which wishes to use only frozen symbols but can tolerate a load-time dependency on xpcom.dll should link against xpcomglue_s.lib and xpcom.lib. It should not link against xpcom_core.lib. This is the case for XPCOM components, because they are loaded into Mozilla which already has full XPCOM loaded and initialized.</p>
<h4 name="Frozen_linkage:_standalone_glue_.28no_DLL_dependencies.29">Frozen linkage: standalone glue (no DLL dependencies)</h4>
<p>Use this when you have a custom application where you want to embed Gecko to show webpages in your own window. I.e. this linkage strategy is used when an embedder needs to bootstrap XPCOM by finding a compatible <a href="/en/GRE" title="en/GRE">GRE</a> on disk and loading it.</p>
<p>In order to use XPCOM, the embedding application first needs to find where the XPCOM runtime is located. This is typically done using <a href="/en/GRE_GetGREPathWithProperties" title="en/GRE_GetGREPathWithProperties">GRE_GetGREPathWithProperties</a>. Then, the code must call <a href="/en/XPCOMGlueStartup" title="en/XPCOMGlueStartup">XPCOMGlueStartup</a>, which will dynamically link against the XPCOM runtime. Only then can the embedding application initialize and use XPCOM.</p>
<p>Embedding code which wishes to use only frozen symbols and cannot tolerate a load-time dependency on <code>xpcom.dll</code> should <code>#define XPCOM_GLUE 1</code> while compiling, and link against <code>xpcomglue.lib</code>. It should <em>not</em> link against <code>xpcomglue_s.lib</code> or <code>xpcom.lib</code>.</p>
<p>Embedders using the standalone glue typically also need to avoid linking against NSPR as well. However, when using <strong>threadsafe</strong> together with the glue libraries from Gecko 1.8 or later, a special step needs to be taken to use <code>NS_IMPL_THREADSAFE_ISUPPORTS<em>n</em></code>. This is because it forces a dependency on the NSPR library, which can otherwise be avoided. As described in {{ Bug("299664") }}, the preprocessor symbol <code>XPCOM_GLUE_USE_NSPR</code> needs to be defined.</p>
<h4 name="Using_Mozilla_internal_linkage">Using Mozilla internal linkage</h4>
<p>Mozilla internal code defines MOZILLA_INTERNAL_API while compiling and links against xpcom.lib and xpcom_core.lib. In almost all cases embedders should *not* use internal linkage. Components using internal linkage will have shared-library dependencies against non-frozen symbols in the XPCOM libraries, and will not work with any other versions of XPCOM other than the one it was compiled against.</p>
<p>Internal linkage will be unavailable to extension authors in XULRunner 1.9 (Firefox 3) because the nonfrozen symbols will not be exported from libxul. Extension and application authors currently using internal linkage should read the guide on <a href="/en/Migrating_from_Internal_Linkage_to_Frozen_Linkage" title="en/Migrating_from_Internal_Linkage_to_Frozen_Linkage">Migrating from Internal Linkage to Frozen Linkage</a>.</p>
<h3 name="Sample_Compiler.2FLinker_Flags">Sample Compiler/Linker Flags</h3>
<p>Code compiled using XPCOM headers should always <code>#include "xpcom-config.h"</code> from the SDK, to ensure that XPCOM #defines are correct.</p>
<p> </p>
<table class="fullwidth-table"> <tbody> <tr> <th>Linking Strategy:</th> <th style="text-align: center;">Dependent Glue</th> <th style="text-align: center;">Standalone Glue</th> </tr> <tr> <th colspan="3">Compiler Flags:</th> </tr> <tr> <th>Cross-Platform</th> <td><code style="white-space: pre;">#include "xpcom-config.h"</code></td> <td><code style="white-space: pre;">#include "xpcom-config.h"<br> #define XPCOM_GLUE</code></td> </tr> <tr> <th>Windows</th> <td colspan="2" style="text-align: center;"><code style="white-space: pre;">/FI "mozilla-config.h"</code></td> </tr> <tr> <th>Linux</th> <td colspan="2" style="text-align: center;"><code style="white-space: pre;">-include "mozilla-config.h"</code></td> </tr> <tr> <th colspan="3">Linker Flags:</th> </tr> <tr> <th>Windows</th> <td><code>-LIBPATH:<var>c:/path/to/sdk/lib</var> xpcomglue_s.lib xpcom.lib nspr4.lib</code></td> <td><code>-LIBPATH:<var>c:/path/to/sdk/lib</var> xpcomglue.lib</code></td> </tr> <tr> <th>Mac</th> <td> <p><code>-L<var>/path/to/sdk/lib</var> -L<var>/path/to/sdk/bin</var> -Wl,-executable-path,<var>/path/to/sdk/bin</var> -lxpcomglue_s -lxpcom -lnspr4</code></p> <p>when building against a XulRunner derived SDK, use: <br> <code>-L<var>/path/to/sdk/lib</var> -L<var>/path/to/xulrunner-bin</var> -Wl,-executable_path,<var>/path/to/xulrunner-bin</var> -lxpcomglue_s -lxpcom -lnspr4</code> <br> where 'xulrunner-bin' is either <code>/Library/Frameworks/XUL.framework/Versions/Current/</code> or <code>/path/to/xulrunner-build/{{ mediawiki.external('platform') }}/dist/bin</code></p> </td> <td><code>-L<var>/path/to/sdk/lib</var> -lxpcomglue</code></td> </tr> <tr> <th>Linux</th> <td> <p><code>-L<var>/path/to/sdk/lib</var> -L<var>/path/to/sdk/bin</var> -Wl,-rpath-link,<var>/path/to/sdk/bin</var> -lxpcomglue_s -lxpcom -lnspr4</code></p> <p>Write it <strong>exactly</strong> as stated, see Notes.</p> </td> <td><code>-L<var>/path/to/sdk/lib</var> -lxpcomglue</code></td> </tr> </tbody>
</table>
<h4 name="Notes">Notes</h4>
<ul> <li>Never link against xpcomglue.lib and xpcomglue_s.lib at the same time.</li> <li>Never link against xpcomglue.lib and xpcom.lib at the same time.</li> <li>For XULRunner 1.9, on Linux you should use either the <code>.pc</code> files. For example: <code>pkg-config --cflags --libs libxul.pc</code></li> <li>These instructions are for Mozilla 1.8 and above. When using a SDK from Mozilla 1.7 or earlier, you must define MOZILLA_STRICT_API when using any form of the glue.</li> <li>Linux and Mac: Make sure the Gecko libraries are listed <strong>after</strong> your object (.o) files on the link line.</li> <li>Linux and Mac: Write the linker options <strong>exactly</strong> as stated (just replacing the <var>/path/to/sdk/</var>), otherwise you get an <code>undefined symbol: ...NS_TableDrivenQI...QITableEntry...</code> at runtime (not compile time) (in debug builds) or your module just won't load (in optimized builds).</li> <li>In principle, <code style="white-space: pre;">#include "mozilla-config.h"</code> should also work, if it's the first <code style="white-space: pre;">#include </code> in .cpp, but preprocessor option is how it's usually included.</li>
</ul>
<h3 name="See_Also">See Also</h3>
<ul> <li><a href="/en/Using_the_Gecko_SDK" title="en/Using_the_Gecko_SDK">Using the Gecko SDK</a></li> <li><a href="/en/Migrating_from_Internal_Linkage_to_Frozen_Linkage" title="en/Migrating_from_Internal_Linkage_to_Frozen_Linkage">Migrating from Internal Linkage to Frozen Linkage</a></li>
</ul>
<p> </p>
Revert to this revision