woof-CE-libre/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.

NOTE June. 18, 2014
-------------------
by 01micko
Woof-CE, a fork of woof2 can build the same as woof2 however a new feature
has been added as of today. It now has the ability to build a distro with out
modules in the initrd.gz, a feature which had been pioneered by Fatdog 
developers kirk and jamesbond. This has a number of advantages over the 
legacy kernel builds.
1. No messy copying kernel modules from the initial ram disk to the root
system.
2. Ease of changing kernels.

I have named this the 'huge' type kernel, for want of a better term. The
rationale for this is that Slackware developers name their default kernel
"huge-$some_suffix". The reason is that the vmlinuz kernel image contains
all the necessary filesystem and hardware drivers to get the system to boot
and hand over to the real running system. Once that occurs, kernel modules
are loaded to bring up the rest of the hardware and extra filesystems if
necessary.
"kernel-kit", part of woof-CE, and a work in progress, now has the ability
to produce one of these 'huge' style kernel packages. Please read the relevant 
README and the comments in "build.conf" inside the kernel-kit directory.

To use this new feature just start woof-gui or 0setup as usual. Run through
the download stage. The 1download now will not to download a legacy style Puppy
kernel. At the 3builddistro stage there is a new button in the 'woof-gui' named
"HUGE BUILD DISTRO". This button invokes an alternate script named
"3builddistro-Z". If using CLI just call ./3builddistro-Z as normal. 
If you have built a "huge" style kernel with kernel-kit then place the package
in the "huge_kernel" directory at the root of your woof installation. If not, 
one will be downloaded for you after you invoke 3builddistro-Z from the 
woof-gui or CLI. You do get a choice of which version you want. Be sure you 
choose the correct architecure. All 32 bit builds are suffixed with either 
i486, i686 or x86. All 64 bit builds are suffixed x86_64. At the end you will 
end up with an iso image, devx and checksums as usual.