====== NSPluginWrapper Help Center ====== FIXME The help center is still under construction. This page is intended to gather various documentation about nspluginwrapper. The documentation is covered by the [[http://creativecommons.org/licenses/by-nc-sa/2.0/|Creative Commons Attribution-NonCommercial-ShareAlike 2.0]] license. Current authors include: . ===== General Notes ===== ==== Features ==== 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 [[http://www.qemu.org/|QEMU]] on Linux/ppc platforms * Run Linux/i386 plugins on FreeBSD and NetBSD platforms * Run Solaris/SPARC Adobe Reader on Solaris/x86 platforms through [[https://train.transitive.com/reader|Transitive QuickTransit for Solaris/x86]] ==== Cross-platform support matrix ==== 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. ^ Host ^ Target ^ Version ^ Comments ^ | Linux/x86_64 | Linux/i386 | 0.9.90.1 | | | Linux/ppc | Linux/i386 | 0.9.90.1 | Experimental, ''qemu-i386'' | | FreeBSD/i386 | Linux/i386 | 0.9.91 | FreeBSD 6.1, FreeBSD 6.2-RC Linux run-time | | NetBSD/i386 | Linux/i386 | 0.9.91 | NetBSD 3.1, ''COMPAT_LINUX'' | | Solaris/x86 | Solaris/SPARC | 1.1.2 | Transitive QuickTransit | ==== Installation ==== * 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. ==== Usage ==== === Configuration program: nspluginwrapper === * 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 === Emulated environment: QEMU === * 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, [[http://www.gaumont.fr/images/fleur.swf|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 [[http://www.gnu.org/software/gnash/|Gnash]] for native Flash 7 support. === Compatibility === 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) ==== Compilation from the sources ==== * 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. ===== Release Notes ===== ==== Version 1.2.0 ==== === Windowless plugins support === 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. === Native plugins support === 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. === Improved security model === 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. === Standalone plugins player === ''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 '''' 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 === Open Solaris support === 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: [[https://train.transitive.com/reader|QuickTransit® for Solaris™/x86 with Adobe® Reader®]] === Development history === You can check the following articles if you want to get further details about what happened during the 1.1.x development cycle: * [[en:blog:2008:12:08:nspluginwrapper_1.1.10|nspluginwrapper 1.1.8 and 1.1.10]] * [[en:blog:2008:11:24:nspluginwrapper_1.1.6|nspluginwrapper 1.1.6]] * [[en:blog:2008:11:07:nspluginwrapper_1.1.4|nspluginwrapper 1.1.4]] * [[en:blog:2008:10:13:nspluginwrapper_1.1.2|nspluginwrapper 1.1.2]] * [[en:blog:2008:07:06:nspluginwrapper_1.1.0|nspluginwrapper 1.1.0]] ==== Version 1.0.0 ==== === Compilation and configure options === 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. === Wrapping root plugins === 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. === WebKit === This release fixes support for WebKit-based browsers. In particular, this should fix [[https://bugs.webkit.org/show_bug.cgi?id=18883|WebKit bug #18883]] whereby plugins were crashing on exit. However, you will also need a recent enough snapshot of WebKit (>= rev 33570, see [[https://bugs.webkit.org/show_bug.cgi?id=18882|WebKit bug #18882]]). === Acrobat Reader 8 === 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. === Flash Player === * 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 [[http://www.addictinggames.com/bloxors.html|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. ==== Version 0.9.91.5 ==== === Improved XEMBED support === NSPluginWrapper now has improved support for plugins using the XEMBED protocol. In particular, this addresses both the [[http://www.multimedia.cx/diamondx/|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. === Fixed focus problems with Flash Player === Debian [[http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=435912|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. === Run-time detect broken 64-bit Konqueror versions === 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. === Support for wrapping 64-bit plugins === 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. ==== Version 0.9.91.4 ==== === Anonymous sockets on Linux systems === 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. ==== Version 0.9.91 ==== === Scripting support through NPRuntime === Scripting support through the [[http://www.mozilla.org/projects/plugins/npruntime.html|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 === Flash Player 9 beta 1 (9.0.21.55) is not supported. [[http://labs.adobe.com/downloads/flashplayer9.html|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. === Biarch build === 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. === Cross-platform improvements === NSPluginWrapper now supports FreeBSD and NetBSD hosts. Please read the [[#platforms_support_matrix|Platforms Support Matrix]] and [[#distribution-specific_notes|Distribution-specific Notes]] sections for further details. ==== Version 0.9.90.4 ==== === Konqueror support === Initial support for Konqueror browser is added in this release. However, you need an x86_64 version built with fixed NPAPI headers. The following [[this>projects/nspluginwrapper/files/kdebase-3.4.2-npapi-64bit-fixes.patch|patch]] was tested for kdebase 3.4.2 and above. === Flash Player 9 Beta === 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, [[http://www.valgrind.org|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. ===== Distribution-specific Notes ===== ==== Mandriva Linux ==== === Installation === * 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. === Compilation from the sources === * 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 ==== Debian GNU/Linux ==== === Installation === * 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 [[http://www.dipconsultants.com/debian/|DIP Consultants]]. ==== Fedora ==== === Installation === * 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. ==== FreeBSD ==== === Installation === * 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 === Compilation from the sources === * 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. ==== NetBSD ==== === Installation === * 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 === Compilation from the sources === * 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. ==== DragonFlyBSD ==== === Installation === * Please refer to the [[#netbsd|NetBSD]] installation instructions. NSPluginWrapper is also available in pkgsrc. ===== Problems... and solutions! ===== ==== Flash Player ==== === Sound support === 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'').