Puppy Unleashed
---------------

Puppy Unleashed consists of all the binary packages of which Puppy
is composed, and a script, createpuppy, to build Puppy Linux.

createpuppy will build the files image.gz and usr_cram.fs and will
also build a live-CD ISO file.

The script needs a temporary 300M working space, so the partition
in which you have placed this Puppy Unleashed tarball must have that
much free memory (after expanding the tarball).
It must NOT be a msdos or vfat partition, as they do not have
adequate file permissions.

The currently running Linux system must be using the same kernel as used
in Puppy. Puppy himself can be used -- that is, download a Puppy
live-CD ISO file from a Puppy download site, bootup Puppy, connect to
the Internet, then download this Puppy Unleashed tarball.

Alternatively, another distro setup to use the same kernel, should be
okay. The Puppy website has a page that explains how to compile the
kernel on Slackware.

To execute createpuppy, login as root (not necessary in Puppy as already
in root), open a terminal window in this directory (that is, the directory
that has this README.txt file), and type this at the commandline:

# ./createpuppy

There is, hopefully, adequate explanation as the script executes.

The first time through, it would probably be best to choose the
default whenever asked for keyboard input, which means just press
the ENTER key. After you have confirmed that it does indeed work,
you can run through it again and play with changes.

A further note on the first time through: the script will report some
packages not selected that may be needed. Don't worry, they aren't.

--------------------------------------------------------------

Package format
--------------

If you want to create your own packages, it's very easy.
A binary tarball, assuming that library dependencies can be satisfied for the
executables, should be readily adaptable for inclusion in Puppy Unleashed.

Directory layout is basically normal. Look at 0rootfs_skeleton-x.x.x package
to see the basic directory hierarchy.

The final Puppy distro has /etc as a link to /root/.etc, however for these packages
you just have a normal /etc directory. The createpuppy build script will relocate
any files in /etc to /root/.etc in the rootfs-complete directory, which is the
complete final Puppy filesystem ready to be turned into a live-CD ISO file.

One different directory is /root0. Place anything in here that is intended to
end up in /root (the user's home directory) in the final distro.

At the top-level in a package, you can have various optional files that will
get removed:

Filename       Purpose
--------       -------
keyword        This has one or more space-separated keywords. These are used for
               the window manager post-install scripts, to build menus.
               Basically, a keyword is the first word that appears in a menu.
               See the pinstall.sh files for Fvwm95 and JWM for more info.
               This file is only required if the package has one or more apps
               that have to be in a menu.
pinstall.sh    This is an optional post-install script.
               Most packages do not need it.
               Look in Fvwm95, JWM, Firefox packages for examples.
               Also look at pinstall.sh in 0rootfs_skeleton-x.x.x package.
filename.xpm   These are optional one or more xpm files that will get moved to 
               rootfs-complete/usr/local/lib/X11/mini-icons/.
               The config files for each window manager use these, for displaying
               in the top-left of application windows and in menus.
               It is recommended that if an application is named, say "rxvt",
               then there be a xpm file named "rxvt.xpm" -- the reason for this is
               that JWM automatically looks for a xpm with the same name as the
               executable to use top-left of window.
               Note, if any image file has format *32.xpm or *24.xpm or *32.png then
               it will be moved it to rootfs-complete/usr/local/lib/X11/pixmaps/.

In the packages directory, each sub-directory, that is, each package, is named
according to a particular convention. For example, "util_linux-2.12".
The original package is named "util-linux", however I have changed the "-" into
and underscore, as I want the package name to be easily separated from the
version number by a script. A "-" is used as delimiter between package name and
the version number.
Use all lower-case letters.

You will also need to create a new line in packages.txt.
Note that the entries are in alphabetical order, but if you create a new line that
is not in alphabetical order then script createpuppy will (or rather is supposed
to) sort the entries. One thing that you will need to decide on is the "group".
Is it in CONSAPPS, XLIBAPPS, GTK1APPS, GTK2APPS, or TCLAPPS group?

There is a section further down that explains the fields in packages.txt.

You can use the "ldd" command on an executable to determine its library dependencies.
You can use the "du" command to find the size of a package, though that will
include sizes of all the subdirectories (as well as their contents).

There is still more work to do, to install a package...
The window managers each have a configuration file with a fully-populated menu, that
is, entries for all applications, but they are all commented-out.
The post-install script for each window manager uses the keyword file from each
package to sift through the config file and uncomment the appropriate menu entry.
You will need to edit the config file for each window manager and add any
applications that you wish to appear in the menu.

The JWM window manager .jwmrc config file is in XML format, but be careful not to
edit this in a WYSIWYG HTML editor, as it may break lines. Each menu entry must be
on one line. Use a text editor.
...no, I tried it in Mozilla Composer (Preferences set to not reformat HTML)
   and it was okay!

No, not finished yet!
Puppy Unleashed also automatically builds the Help file, located in the package
0rootfs_skeleton-x.x.x, in directory usr/share/doc/index.html.
The build script will copy this to rootfs-complete/usr/share/doc/index.html.
This is the same principle as for the window manager menus -- entries are
commented out, and the post-install script in 0rootfs_skeleton-x.x.x will
uncomment appropriate lines.
if you add a new package, also add a line in this file.

The index.html Help file is in HTML format, but be careful not to edit
this in a WYSIWYG HTML editor, as it may break lines. Each help-file entry must
be on one line. Use a text editor.
...but, Composer seems to be okay, see my note above.

-----------------------------------------------------------------------

Compression
-----------

The file image.gz is a compressed file. Uncompressed, it is a 11264K ext2
filesystem. This filesystem has all the directories except for /usr.
"image" loads when Puppy boots, into a ramdisk, and it is the "/" of the
Puppy filesystem.

Unlike /user, it runs in ramdisk uncompressed.

If you look at rootfs-complete folder, you will see directory root0, and
this has about 2.5M of stuff in it. The first time that Puppy boots on a PC,
the file "pupxxx" is created on the PC's hard drive, mounted on /root and all
of /root0 copied to it, then /root0 is deleted.

So, everytime Puppy boots, /root0 is there, and gets deleted, freeing up
2.5M in the ramdisk. However, as file "image" has /root0, it is chock full.
You may overrun the 11264K f.s. if you install more packages.

The size of "image" could be increased, however for now that size is necessary
as that is the size that the kernel is compiled for /dev/ram0, /dev/ram1, etc.
(though that can be overridden by ramdisk_size= kernel boot option).

One quick fix to make more space is to compress the executables in /bin and
/sbin, at least some of them.
I have included the "upx" executable compressor, which does a very good job.
Gawk for example, is 245K uncompressed, and 107K compressed.
In fact, I have done it for gawk -- look in the post-install script of the
gawk package.

-----------------------------------------------------------------------

packages.txt
------------

The format of this is straightforward. For example:

"gxine-0.3.3" "gxine-0.3.3: GUI multimedia player, Xine frontend" on "MMGTK2APPS" \

This is one line from packages.txt. The first field (leftmost) is the package
name and is exactly the same as a directory in packages/ folder.

The second field is the information field that is displayed by createpuppy.

The third field can have value "on", "off" or "unavailable".

The last field may have nothing, in which case it is simply "", or it can have
a group classification, for example MMGTK2APPS.
It can also have more sections, for example:

 "MMGTK2APPS 900K"

which gives the uncompressed size of the package. Another example:

 "MMGTK2APPS +xine-1.0 900K"

The middle sub-field is a comma-delimited list of dependencies.
Each element in this list is a package name preceded by a +, -, or |.
 + means that the package is required.
 - means the package must not be installed.
 | means either package but not both.
HOWEVER, none of this is implemented yet.

In the above example, gxine-0.3.3 belongs to MMGTK2APPS group, meaning
that it is a multimedia GTK2 application. Therefore all the packages in
CONSCORE, GTK2CORE and MMCORE groups should be installed.
However, this is very coarse, and for example, you may not want all
the MMCORE packages installed. The "+xine-1.0" is informing that gxine
absolutely must have that xine package (xine is a MMCORE package). 
So, the createpuppy script can warn you, if you remove xine, that gxine
is not going to work. 
...NOT YET IMPLEMENTED.

UPDATE APRIL 2005:
Puppy version 1.0.1 has a new PupGet package manager, that now reads the
"+pkgname" subfield, for example:

 "GTK2APPS +xine-1.0,+bash-3.0 900K"

Regards,
Barry Kauler
http://www.goosee.com/puppy
Feb 2005

