NSPluginWrapper Help Center

The help center is still under construction.

This page is intended to gather various documentation about nspluginwrapper.

The documentation is covered by the Creative Commons Attribution-NonCommercial-ShareAlike 2.0 license. Current authors include: <mail-me for login>.

NSPluginWrapper makes it possible to use Netscape 4 (NPAPI) plugins on platforms where they were not built for. Sample use cases include but are not limited to:

• Run Linux/i386 plugins (e.g. Flash Player, Acrobat Reader) natively on Linux/x86_64 platforms
• Run Linux/i386 plugins through QEMU on Linux/ppc platforms
• Run Linux/i386 plugins on FreeBSD and NetBSD platforms
• Run Solaris/SPARC Adobe Reader on Solaris/x86 platforms through Transitive QuickTransit for Solaris/x86

nspluginwrapper supports native plugins fine but its primary use is to execute plugins that are not of the same architecture and/or operating system than the running browser.

• On package installation, 32-bit plugins are automatically recognized and installed system-wide, provided they are available in the /usr/lib/mozilla/plugins directory.

• You can then manually install/remove/update plugins with the nspluginwrapper program.

• Installing an additional plugin (e.g. the JPEG2000 plugin) into the user's Mozilla plugins directory:

  nspluginwrapper -i ~/downloads/npjp2-0.0.2/src/npjp2.so

• Updating (with detailed information – verbose mode) all installed plugins from the system and user's directories:

  nspluginwrapper -v -a -u

• Removing a plugin:

  nspluginwrapper -r ~/.mozilla/plugins/npwrapper.npjp2.so

• Note that QEMU currently does not support NPTL. Please use a non-NPTL glibc, or remove the tls directories from your emulated environment, or patch /usr/lib/nspluginwrapper/npviewer so that it sets a suitable LD_ASSUME_KERNEL variable.

• Using QEMU is a nice proof-of-concept for running nspluginwrapper on non x86 platforms. However, you may notice poor performance. For example, Gaumont fleur.swf renders at most 2 frames per second on my Powerbook G4/400, at best. Typical performance is rather 1 to 2 seconds per frame. Alternatives are: adding AltiVec optimizations to SSE emulation and/or get the Ciel project author to revive his JIT. You can also consider Gnash for native Flash 7 support.

The following plugins work reasonnably well natively, and at a lesser extent in emulated mode:

• Acrobat Reader (5.0.9, 7.0.1, and 8.1.2)
• DejaVu Libre (3.5.14)
• Flash Player (7.0, 9.0 and 10.0)
• Linux JPEG 2000 (0.0.2)
• Mplayerplug-in (2.80 and 3.25)
• Real Player (10.0.5)
• ICA Citrix Client
• Squeak VM (3.7)
• Tcl/Tk (3.1.0)

• Make sure you have the necessary GTK+-2.0 development libraries and headers.

• Build the Viewer on a Linux/i386 (target) platform:

  $ ./configure && make npviewer.bin

• Build and install the Wrapper plugin on your current (host) platform:

  $ ./configure && make
  # make install
  

• Manually copy the npviewer.bin program to your installation directory, typically /usr/lib/nspluginwrapper/i386/.

• Note: on distributions capable of 32-bit development on x86-64 without chroot (e.g. Mandriva Linux), both the Wrapper and Viewer components can be built at once. It is enough to run configure with the –enable-biarch option.

• Note: when building the viewer on a Linux system and if it is intended to actually run on another OS (e.g. NetBSD, FreeBSD), you will have to configure your Linux build with the –enable-generic option.

Windowless plugins are now supported in Firefox 3. Only Flash Player 10 and a modified DiamondX plugin were tested. There currently is no means to disable windowless plugins at run-time. Though, this can be changed at compile-time through the ALLOW_WINDOWLESS_PLUGINS macro in npw-viewer.c. Also note that, sometimes, popup menus triggered by a right-click won't show up. Likewise, you may also experience a few browser window redraw quirks while navigating through Gtk2 modal dialogs raised by the plugin.

It is now possible to wrap native plugins with the -n or –native option to the nspluginwrapper configuration utility. This can be useful for safety purposes (the plugin crashes, not the browser) and for security purposes (the plugin accesses only what it is allowed to). Red Hat has been using nspluginwrapper for all architectures for a couple of releases now, along with an SELinux policy. Experienced users could also give alternatives a try, e.g. RSBAC's jail functionality.

The plugins system is now restarted when an error is encountered. This is not fully automatic though. i.e. if a plugin crashed, you have two options to restart it: (i) reload the page, (ii) wait for a refresh requested by the page (through some javascript or whatever triggers an NPP_New() call). You no longer have to restart the browser!

Measures were also taken to not expose extraneous open files descriptors to the plugins. i.e. if a plugin examines the set of open files at its creation, it won't notice anything.

nspluginplayer is a new application that enables you to execute a plugin without a browser. This can be useful for Flash presentation or… simply debugging. The player does not emulate the whole NPAPI but enough is implemented to support Flash Player, Acrobat Reader. Usage is very simple: nspluginwrapper embed-args whereby embed-args are the arguments from an <embed> tag. Here are some examples to demonstrate the program.

• Play a Google video:

  $ nspluginplayer style="width:400px; height:326px;" id="VideoPlayback" type="application/x-shockwave-flash" src="http://video.google.com/googleplayer.swf?docId=-7309713943323243972&hl=en-GB" flashvars=""

• Play a Flash game:
  

  $ nspluginplayer src=http://magic.pen.fizzlebot.com/magic-pen.swf width=800 height=520

• View a PDF document:
  

  $ nspluginplayer src=/path/to/some/file.pdf

This is the first version to officially support Open Solaris hosts (2008.xx, in particular). Transitive is also using nspluginwrapper, though an earlier build, to allow Solaris/x86 users to use the Adobe Reader plugin for Solaris/SPARC in their browsers. You can find more information on this (free) application here: QuickTransit® for Solaris™/x86 with Adobe® Reader®

You can check the following articles if you want to get further details about what happened during the 1.1.x development cycle:

• nspluginwrapper 1.1.8 and 1.1.10
• nspluginwrapper 1.1.6
• nspluginwrapper 1.1.4
• nspluginwrapper 1.1.2
• nspluginwrapper 1.1.0

Some –with options were moved to –enable style. In particular, –enable-biarch replaces –with-biarch and –enable-generic replaces –generic-build. Besides, the binaries are no longer stripped by default. Should you wish to strip the installed files, you should configure with the –enable-strip option.

Previous versions of nspluginwrapper used to incorrectly wrap root plugins system-wide. The fix introduced in this version is very minimalistic and works as follows: any plugin located under ~root will be wrapped into his private plugins directory (~root/.mozilla/plugins). If a wrapped root plugin is found in any system location during upgrade, it will be moved to the ~root private location instead.

This release fixes support for WebKit-based browsers. In particular, this should fix WebKit bug #18883 whereby plugins were crashing on exit. However, you will also need a recent enough snapshot of WebKit (>= rev 33570, see WebKit bug #18882).

A bug was introduced in version 0.9.91.5 which prevented Acrobat Reader 8 (8.1.2) from working correctly: no keyboard event was propagated to the plugin. This is now fixed.

• This release includes a fix for Flash Player 9 on Linux SMP/CMP systems.

• There are some (unresolved) threading issues with Flash Player 9 on *BSD systems, in particular FreeBSD 6.1 and NetBSD 3.1. Pages with only one Flash instance will work though multiple instances will fail because of multithreading. This may be an issue with the Linux emulator on those systems. Probably some TLS stuff or some Linux syscalls unsufficiently supported. BSD hackers should probably look into waitid, tgkill, futex syscalls and also coverage of newer CLONE_* flags.

• Flash Player 10 Beta for Linux is working but you may encounter keyboard input problems with some sites. In particular, the usual Bloxorz game^W testcase at Addicting Games is failing again with this Beta. This is not an nspluginwrapper problem but a generic issue with Flash Player 10 Beta that also occurs with 32-bit web browsers.

NSPluginWrapper now has improved support for plugins using the XEMBED protocol. In particular, this addresses both the DiamondX XEmbed example plugin and Flash Player 9 Update 3. Note that Konqueror NPAPI emulation layer still doesn't support the XEMBED protocol, so this only works for Mozilla-based browsers.

Debian bug #435912 is about Flash Player grabbing the keys from other windows even if the Flash Player window lost the fous. The way nspluginwrapper handles input focus has now changed and thus also removing some other (rare?) crashes. However, this curently relies much on XEMBED support. And, since Konqueror doesn't implement it yet, this bug is still available there. I also suspect Flash Player is not totally innocent to this problem.

Support for Konqueror was added in version 0.9.90.4. However, it required an additional patch to get 64-bit Konqueror on-par with NPAPI defined types. Now, nspluginwrapper will try to detect broken 64-bit versions of Konqueror at run-time and should be able to address both cases from a single binary. The heuristics are quite reasonable, please report otherwise.

Martin Stransky from Red Hat Engineering has added support for 64-bit plugins, among other things to be integrated in a future release. This means you can wrap both i386 and x86_64 plugins into an x86_64 browser. This is so that you can let a crashing plugin die alone without bringing the browser with him into the grave.

NSPluginWrapper now use anonymous sockets on Linux systems. This doesn't change the run-time behaviour of NSPluginWrapper. However, if you are a distributor or someone who wants to rebuild the packages himself, you have to know that Linux binaries intended to run on other OS have to be built with the –generic-build option. Otherwise, native Linux builds now use anonymous sockets by default.

Note: packages available on this website still use named sockets so that they can be reused verbatim on *BSD systems.

Scripting support through the npruntime API is now supported. You can disable npruntime with the NPW_DISABLE_NPRUNTIME environment variable. Please note that Konqueror does not currently support this API. So, this will only work with Mozilla-based browsers.

Flash Player 9 beta 1 (9.0.21.55) is not supported. Flash Player 9 beta 2 (9.0.21.78) will work correctly, including with sites using javascript to navigate through other pages. There is a check to prevent the use of FP9 beta 1.

Most of Linux/x86_64 distributions can't build biarch (i.e. 32-bit and 64-bit) packages at once. Henceforth, a subset of LSB Desktop 3.1 is now included so that the 32-bit viewer can be built effortlessly. You only have to make sure that your compiler supports generation of -m32 code.

NSPluginWrapper now supports FreeBSD and NetBSD hosts. Please read the Platforms Support Matrix and Distribution-specific Notes sections for further details.

Initial support for Konqueror browser is added in this release. However, you need an x86_64 version built with fixed NPAPI headers. The following patch was tested for kdebase 3.4.2 and above.

Flash Player 9 beta for Linux does not work correctly yet. In particular, the plugin will crash on ButtonRelease events (in an XtDispatchEventToWidget callback) when the button represents a link to another page. Independently, Valgrind reports a very high number of use of uninitialised value, conditional jump or move depends on uninitialised value and similar errors. It's not known yet whether this is caused by nspluginwrapper or not.

• In native mode (x86_64), please use the Mandriva Linux packages. urpmi will get the necessary dependencies even for 32-bit packages provided you have an i586 media available.

• In emulated mode (ppc, ia64, etc.), you may want to install the nspluginwrapper-i386 package with –ignorearch, if you don't want to regenerate that package for your architecture. Make sure you have a GTK+-2.0 capable emulated environment and any other library required by your plugins. A convenience script – /usr/lib/nspluginwrapper/mkruntime – is available to help you install a 32-bit runtime from a Mandriva Linux 2006.0 RPMs repository.

• Building on x86-64 requires Mandriva Linux LE2005 or newer for more convenient operations:

  # urpmi gtk2-devel 'devel(libgtk-x11-2.0)'
  $ rpm --rebuild --with biarch nspluginwrapper.src.rpm
  

• On non x86-64 platforms, you have to generate nspluginwrapper-i386 from the nspluginwrapper.i586.rpm package with repackage.sh:

  $ NSPLUGINWRAPPER_SOURCES/utils/repackage.sh /FULL_PATH/nspluginwrapper.i586.rpm
  

• Rob Andrews contributed Debian packages to unstable / utils. You are invited to use those packages instead of (inappropriately?) using alien to convert RPM packages to Debian package format.

• Debian 'Etch' users can also install the packages from DIP Consultants.

• NSPluginWrapper is now included in the main Fedora repositories. You should use those packages as they do fit better the Fedora build and run-time policies.

• You need a 32-bit Linux/i386 run-time capable of executing GTK+2.0 binaries. On a FreeBSD 6.1 system, it is possible to install the following packages from FreeBSD 6.2-RC: linux-atk, linux-expat, linux-fontconfig, linux-glib2, linux-gtk2, linux-jpeg, linux-pango, linux-png, linux-tiff, linux-xorg-libs, linux_base-fc-4.

• RealPlayer 10 (tested 10.0.8.805).

  # make -C /usr/ports/multimedia/linux-realplayer install clean

• Flash Player 7 (tested 7.0.68).

  # make -C /usr/ports/www/linux-flashplugin7 install clean

• Adobe Reader 7 (tested 7.0.8).

  # make -C /usr/ports/print/acroread7 install clean

• Then, installing the plugins system-wide into /usr/X11R6/lib/browser_plugins is made easy.

  # nspluginwrapper -v -a -i

• The configure script will auto-detect FreeBSD and thus won't build the Linux/i386 viewer. You have to build the viewer on a Linux/i386 system with the –generic-build option or extract it from the nspluginwrapper-i386 RPM package available here.

• The easy way is to use the NetBSD Packages Collection (pkgsrc) framework to build released NSPluginWrapper packages. Please update your local tree. Otherwise, here are a few hints for reference.

• You need a 32-bit Linux/i386 run-time capable of executing GTK+2.0 binaries. On a NetBSD 3.1 system, it is enough to install the suse_gtk2-10.0 package as it will install the necessary dependencies. Note that you may also need the suse_compat-10.0 package as it provides the necessary libstdc++.so.5 for Real Player.

• Real Player 10 (tested 10.0.8.805).

  # cd /usr/pkgsrc/multimedia/RealPlayerGold && make install clean

• Flash Player 7 (tested 7.0.68).

  # cd /usr/pkgsrc/multimedia/ns-flash && make install clean

• Adobe Reader 7 (tested 7.0.8).

  # cd /usr/pkgsrc/print/acroread7 && make install clean

• Adobe Reader 5 (tested 5.10).

  # cd /usr/pkgsrc/print/acroread5 && make install clean

• Then, installing the plugins system-wide into /usr/pkg/lib/firefox/plugins is made easy.

  # nspluginwrapper -v -a -i

• The configure script will auto-detect NetBSD and thus won't build the Linux/i386 viewer. You have to build the viewer on a Linux/i386 system with the –generic-build option or extract it from the nspluginwrapper-i386 RPM package available here.

• Please refer to the NetBSD installation instructions. NSPluginWrapper is also available in pkgsrc.

FlashPlayer 9 now uses the ALSA sound system. As such, you will need the Linux/i386 alsa libraries on your system to get sound working. Generally, on decent-enough distributions, the FlashPlayer package has the needed dependency (e.g. libasound.so.2).