README-FIRST

Woof2 README
------------

*PLEASE READ ALL OF THIS, INCLUDING THE EXTRA NOTES*

Woof2 has two major enhancements over "Woof1":

1. Supports multiple architectures (exs: x86, arm)
2. VCS (Version Control System) friendly

This is achieved by splitting the 'woof-tree' of Woof1 into three directories
'woof-arch', 'woof-code' and 'woof-distro':

woof-arch:  architecture-dependent (x86, arm) files, mostly binary executables.
woof-code:  the core of Woof. Mostly scripts.
woof-distro: distro-configuration (Debian, Slackware, etc.) files.

To create a working directory, named 'woof-out_*', that you will then use just
like you did before with Woof1, you first have to run the 'merge2out'
script. This merges the three directories into a directory named 'woof-out-*'.
You then 'cd' into woof-out_* and run the usual Puppy build scripts.

The great thing about this merge operation is that you can choose exactly what
you want to go into woof-out. You can choose the host system that you are building
on (usually x86), the target (exs: x86, arm), the compatible-distro (ex: debian),
and the compat-distro version (ex: squeeze).
So, you create woof-out without any confusing inappropriate content.

The script 'merge2out' has further explanation of the VCS support,
but basically, 'woof-code' content has been modified to make it VCS-friendly.
A VCS such as Fossil will be able to handle the dirs 'woof-arch', 'woof-code'
and 'woof-distro'.
The 'merge2out' removes those VCS-friendly features from woof-out, so that
woof-out is restored to a normal Woof build environment.
For example, woof-code has a file named 'EMPTYDIRMARKER' inside every empty
directory, and these are removed from woof-out.
Another example, woof-code/boot/initrd-tree0 and woof-code/rootfs-skeleton has
'dev' directory converted to *DEVDIR.tar.gz tarballs (and stored in woof-arch),
as VCS's cannot handle device nodes.

So, to get going with Woof2, open a terminal inside 'woof2' and do this:

# ./merge2out
# cd ../woof-out_<REST OF DIRNAME>

Regards,
Barry Kauler
Nov. 24, 2011
bkhome.org/blog

NOTE Nov. 25, 2011
------------------
Directory woof-code has a lot of binary files in it, but git, svn, mercurial and
fossil all support binary files -- in fact they feature automatic detection of
binary files. Note, cvs has very limited support for binary files.

I was going to move all binary files from woof-code to woof-arch, thinking to have
all binary files in woof-arch only, and started some code in script 'vcs-workarounds'
(commented out). The thinking was that woof-arch could be left out of the VCS if it
does not support binary files, but as most do, I decided that it is an unnecessary
complication.

I did a bit of research and found that a lot of projects store binary files in
their VCS, so Woof is not so unusual.

So, woof-code is allowed to have architecture-independent binary files, such as
images. woof-arch has architecture-dependent binary files, such as executables
for x86 or arm.

NOTE Nov. 26, 2011
------------------
Woof1 was for building an x86-based Puppy only. Woof2 inherits all of that, so
can be used for x86 "build" and x86 "target" environments. When you run the
'merge2out' script, do not choose anything else. 

I am currently working on x86-build, arm1176jzf-s-target, but it is not yet
complete. Basically, more arm packages are needed to build a working Puppy.
I am working on an arm Dpup, using Debian Squeeze compatible-distro binary
packages.