=================================================================

Netscape Plugin for Squeak on Unix platforms


Author:	     Bert Freudenberg 
Last edited: 2010-05-11 17:30:59 by bert

================================================================

Files:
	CMakeLists.txt
	README.npsqueak
	npsqueak.c
	npunix.c	(modified copy from Netscape Plugin SDK)
	include/*	(unmodified headers from Netscape Plugin SDK)
	test/*

=================================================================


	The Squeak plugin should be automatically compiled and installed with 
	the normal squeak build process. This installs squeak into (probably) 
	
		squeakdir=/usr/local/lib/squeak

	You will need an image. Copy it (or symlink) to

		${squeakdir}/SqueakPlugin.image

	A good place to look for an image suited as plugin is

	http://squeakland.org/download		

	To register the plugin run ${imgdir}/npsqueakregister. 
	It looks for various browsers
	in various directories and creates links to the plugin. If
	your browser is not found, hack the npsqueakregister script or
	symlink the plugin manually:

		ln -s ${squeakdir}/@VM_VERSION@/npsqueak.so \
			/usr/lib/mybrowser/plugins/

  	Exit and restart the browser. Check if the Squeak plugin 
	was recognized by selecting the Help>>About Plugins menu item.

  	Open the html file in the test/ directory. This should
	activate the Squeak plugin. Since this is the first time the
	plugin is executed, a .npsqueak folder will be created in your 
	home directory.

=================================================================

NOTE: If you are not the super user of your machine you can install
everything into your home directory. Put npsqueak.so somewhere your
browser will find it.  Make a .npsqueak dir in your home directory
with subdirectories and files like shown below. Also create a
.npsqueak/npsqueakrun file which points to a Squeak VM.

=================================================================

DOCUMENTATION

* How the plugin works:

    - npsqueak.so needs to be symlinked where the browser expects plugins
    - when the browser wants to display a page with an embedded Etoys
      project, it launches the plugin
    - the plugin executes the "npsqueakrun" script, passing some parameters
      to establish a communication channel between the plugin and squeak
    - that script runs the Squeak VM with an image, instructing the VM to
      redirect the output into the plugin's window
    - the image then loads the project

* On the first run for each user, npsqueakrun will create a directory
  structure like this (unless overridden by variables, see below):

    $(HOME)/
    |
    +--- .npsqueak/
    |    |
    |    +--- secure/
    |
    +--- Squeak/


* Environment Variables:

    SQUEAK_USERDIR
	Identifies the sandbox directory, e.g., a place which can be
	accessed from any (potentially unsafe) Squeaklet.  

	* Default: "$(HOME)/Squeak"

    SQUEAK_SECUREDIR
	Identifies the directory to store private information
	like signing keys.

	* should not be accessible by other users

	* Default: "$(HOME)/.npsqueak/secure"

    NPSQUEAK_DEBUG
	If set, logs debug info to /tmp/npsqueak.log

	* Default: unset

* Mimetypes:

    application/x-squeak-source:sts:Squeak source
    application/x-squeak-object:sqo:Squeak object
    application/x-squeak-project:pr:Squeak project

* Parameters:

  parameters in EMBED tag used by Squeak:

    SRC=...
    MEMORY=... (not by unix npsqueak)
    FAILUREURL=...
    IMAGENAME=... 

* Communication with VM is via Pipes

=================================================================

TODO

* loop on read() and write() until all data is sent and received.
* make plugin not wait for browser when the url is loaded into a target.

=================================================================

Change log

May 2010:
	* use CMake
	* default to ~/Squeak
	* do not copy image to ~/.npsqueak anymore

Aug 2009:
	* (ikp) BSD-friendly Makefile

Sep 2007:
	* (bf) use "find -H" in npsqueakregister

Sep 2006:
	* (ikp) use libtool to build

Jan 2005:
	* npsqueak checks for image file in system and home dir
	* modified npsqueakrun, runs with bash, other shells untested
	* renamed untrusted -> My Squeak
	* fixed make sure Squeak really gets killed
	* fixed crashing the browser when closing plugin page

Apr 2004: 
	* (ikp) handle imageName and failureUrl tags

Oct 2002:
	* modified install from home directory to system-wide

Sep 2002:
	* hack to work with Mozilla >= 1.0 which deletes the delivered
	  file immediately. We just create a hard link before and
	  delete that after opening the file.

Mar 2002:
	* uses aio now for command pipe 
	* moved stuff from ~/.netscape/squeak to ~/.npsqueak directory
	* implemented SecurityPlugin

May 2001:
	* updated for squeakland.org image.
	* TODO: SecurityManager

Feb 2001:
	* updated for Squeak 3.0

Nov 2000:
	* introduced -browserPipes command line
	* this fixed the bug of plugins in tables
	* cleaned up a lot of hacks
	* this fixed crashing Mozilla 0.6
	* made widget destroy work more often than not
	* Problems: crashes when closing Netscape window
	*           pipe is polled for now - should use select in sqXWindow


Apr 2000:
	* url requests through browser

Nov 1999
	* report attributes to vm

Aug 1999
	* initial version


