This guide instructs you how to create your own, customized Puppy using a tool called Woof, that is used to create official Puppies.
Notes:Changelog, Iguleder wrote: 2/10/09: first version.
- It requires some Linux experience and knowledge with computers.
- If you have lots of RAM (GBs of memory), you can follow the tutorial in a live session. The ./2createpackages and ./3builddistro steps work way faster from RAM. On my PC, the ./2createpackages stage takes about 40 minutes when I run Woof from my hard drive, and less than 5 minutes from RAM. When you're finished, you can copy the Woof directory to your hard drive.
- I suggest you to have a virtual machine installed somewhere or a spare flash drive, to test your Puppy.
Requirements:
- Time, lots of time. On my Core 2 Duo, 2 GB RAM machine with a fast internet connection, it takes about 4 hours.
- Risky. A lil' bit risky.
- A fast PC. If you own 2 PCs, and you want a custom, small Puppy for your old PC, for example, I'd suggest you to build it on the newer PC.
- A fast internet connection.
- Lots of space on your hard drive, Barry recommends at least 10 GB, I recommend 2 GB.
- A running (!!!) Puppy 4.x with the lzma package installed (install icon on your desktop). 4.3 includes it by default.
___________________________________
Step 1: set your goals.
Decide what's your mission. What's special about your future custom-Puppy? Who should use it, and why?
Here's an example.
I don't like the vanilla Puppy 4.3. The new 2.6.30.5 kernel is problematic on my relatively new PC, and the older 2.6.25.16 kernel from Puppy 4.2.1 was fantastic. I made my custom 4.3's with Woof, with the new kernel, but all had some issues, like missing sound card modules and buggy network card detection.
Oh, yes, and I like Puppy 4.1.2's themes. The Gradient-grey themes, the Icelandic wallpaper and the Stardust icons.
Additionally, I use Puppy from my flash drive too, and I want it to be able to boot from virtually any PC, so I want support for older PCs too, including PCs with SCSI and analog modems.
My Puppy will be called Pituch (a male chicken in Russian).
- Pituch will be based on Puppy 4.3, it will include all Puppy 4.3's default applications.
- Pituch will use Linux kernel 2.6.25.16.
- Pituch will use the Stardust GTK theme, the Stardust icon theme and the Icelandic wallpaper, so it looks like Puppy 4.1.2.
- Pituch will include all modules, for maximal hardware detection.
- Pituch will have only one SFS, pup-xxx.sfs. No zdrv.
- Pituch will be familiar to Puppy 4.1.2 users and people with old hardware.
Now, when you know what you want, you can proceed.
___________________________________
Step 2: download Woof.
At the moment, the only Woof-built Puppy is 4.3, because Woof is still new. Puppy 4.3 (and later Puppies, when they're out) comes with a set of scripts called Woof, that was used to build it from PET packages.
Download the Puppy 4.3 Woof or get another one yourself.
Save it to somewhere, i saved mine in /mnt/home (my hard drive, so it doesn't waste valuable space in the save file).
Enter the console (console icon on your desktop) and run cd <location of woof-something.tar.gz> (in my case it's cd /mnt/home) and tar xzvf woof*tar.gz. This will unpack Woof.
___________________________________
Step 3 (optional): download and install the devx module.
This step is optional, the devx module is required only for the strip command. It allows you to "strip" executables and libraries to make them smaller.
Download the devx module that matches your Puppy version and save it where pupsave.2fs is (usually /mnt/home).
- Puppy 4.3: here.
- Puppy 4.3 Retro and Retro-Retro: here.
- Puppy 4.2.1: here.
- Puppy 4.1.2: here.
- Puppy 4.0: here.
Reboot Puppy.
When your desktop shows up, if this is your first save, the boot manager should appear. If it doesn't, run it through System -> BootManager and click the button near "Choose which extra SFS files to load at bootup".
Add devx-xxx.sfs (by selecting the entry and clicking Add) and reboot.
Now go to the console and run gcc. If you see the message "gcc: no input files", the modules are installed properly.
___________________________________
Step 4: configure Woof.
Open /root (using Rox, file icon on your desktop) and click the Woof directory.
You'll see a bunch of files with weird names.
- The files 0setup, 1download, 2createpackages and 3builddistro are scripts, which we are going to execute, step-by-step.
- The files DISTRO_PKGS_SPECS-something are lists of packages to include in Puppy.
- The files Packages-puppy-something-official are lists of all the PETs that can be used.
- The file DISTRO_SPECS contains the Puppy version and basic details that need to be changed.
Open DISTRO_SPECS with any text editor (right-click it -> Open As Text).
- DISTRO_VERSION is Puppy's version. You can put any 3-digit number here. I suggest you to leave it, so you remember what Puppy version is the base for your custom Puppy.
- DISTRO_BINARY_COMPAT is the distribution to be used to build Puppy from. It can be either Puppy, Debian, Arch or Slackware (lowercase). Building Puppy from another distros requires experience with Linux, because things are missing, incompatible and buggy.
- DISTRO_COMPAT_VERSION is the the version of DISTRO_BINARY_COMPAT that is used. For example, to build Puppy from Slackware 12.2 packages, DISTRO_BINARY_COMPAT should be set to slackware, and DISTRO_COMPAT_VERSION should be set to 12.2.
- DISTRO_NAME is the name of the generated Puppy. It appears in the help pages and various messages (the shutdown message, for example).
- DISTRO_FILE_PREFIX is the prefix for pup-xxx.sfs and the ISO. For example, if DISTRO_FILE_PREFIX is lol and DISTRO_VERSION is 567, pup-xxx.sfs will be named lol-567.sfs.
Here's an example.
I want the version number of my custom Puppy to be 4.3.0, so I put 430 in DISTRO_VERSION. Additionally, I want my Puppy to be built from Puppy packages of the 4.x series, so I change DISTRO_BINARY_COMPAT to puppy, and DISTRO_COMPAT_VERSION to 4. My Puppy will be called Pituch and I want the main SFS to be named pit-430.sfs instead of pup-430.sfs, so I change DISTRO_NAME to Pituch and DISTRO_FILE_PREFIX to pit.
Now let's have a look at DISTRO_PKGS_SPECS-puppy-4. Pituch is built from Puppy 4.x, so I edit this file. The other DISTRO_PKGS_SPECS-something files are used for other DISTRO_BINARY_COMPATs. DISTRO_PKGS_SPECS-slackware is used for a Slackware-based Puppy, for example.
This file is a list of all packages that will be included in Pituch. All the entries in this are written using a certain syntax.
Here's an example of one entry: yes|ayttm|ayttm|exe. Each of the DISTRO_PKGS_SPECS-something files contains more detailed instructions how to write and edit entries in the comments on the top of the file, I'll cover just the basics.
- yes - do you wish to include this package in the custom Puppy?
- ayttm - name of the PET package to use.
- ayttm - the name used by DISTRO_BINARY_COMPAT for the specific package. For example, Puppy and pretty much everyone use the name Firefox, however, Debian calls it Iceweasel, so the entry needs to be changed to yes|firefox|iceweaselsomething on a Debian-based Puppy.
I wish to remove all icon themes and add Stardust, so I applied some changes:
no|desk_icon_theme_blue_moon||exe
no|desk_icon_theme_brown_marble||exe
no|desk_icon_theme_jq8flat||exe
no|desk_icon_theme_original|desk_icon_theme_original|exe
no|desk_icon_theme_silver_marble||exe
no|desk_icon_theme_smooth_color||exe
yes|desk_icon_theme_stardust||exe
I set all the icon theme packages to no, so they're not included, and changed the no near the Stardust icon theme to yes. I did the same thing with GTK themes (just search for gtk_theme inside the file).
___________________________________
Step 4: download all packages.
Now, when we know which packages to include, we can proceed to the actual download. Use the console opened earlier, or just run it (console icon on your desktop, then run cd <location of woof-something.tar.gz>/woof*).
Run ./0setup. This will download all packages lists (it will also process them with any DISTRO_BINARY_COMPAT other than Puppy, takes lots of time) and offer you to upgrade some packages to newer ones, found in other lists.
When some newer package exists, Woof will offer you to upgrade, by entering the package's number and pressing enter. You can press enter without entering a number to decline.
I always press enter to accept all the default packages. In my case, it offered me to upgrade something related to printing, I agreed, and that made my AbiWord crash when I clicked the "print" button.
Now run ./1download and let it download all the packages. This will take some time. You may find out that some packages are missing, you'll have to download and put them in the right places manually. Use Google.
___________________________________
Step 5: extract the packages.
Run ./2createpackages. This will extract all packages and prepare them for inclusion in Puppy. This takes a while ...
Just let it do whatever it does.
___________________________________
Step 6: build Puppy.
It may vary, depending on the Woof used and the kernel version used. Just read the instructions carefully.
You first choice will be the kernel version to use. Older kernels are better for old hardware, while newer ones are better with newer hardware, but work with both. However, some people with old hardware, for example, with a single-core processor claim that newer kernel are problematic on their PCs. Just one example - some say that kernels compiled with SMP (2.6.30.5, in our case) made their single CPU's temperatures go up. I have a dual-core CPU and 2 GBs of RAM, and I stick with the 2.6.25.16, because it's stable and works perfectly with all my hardware. I use another custom Puppy with the 2.6.30.5 for compiling stuff and messing with Woof, because it takes advantage of my CPU and makes things go faster.
Two things that I wish to note:
- All kernels before 2.6.28 do not support the ext4 file system.
- Some kernels are compiled with SMP. They're generally better for multi-core CPUs (other kernels recognize and utilize only one core, that results in lower performance).
After the "Now building sandbox3/rootfs-complete, with the complete filesystem... " stage, the basic Puppy files are put in the sandbox3/rootfs-complete directory. When Woof pauses and asks you to press enter, you can add custom files and modifications to the actual Puppy files. I deleted some files that I find useless, for example.
Here's the list of my decisions:
- I chose to bypass the dependency check.
- I chose to include SCSI drivers.
- I chose to keep the "other" framebuffer modules and the "exotic" modules.
- I chose to keep all modules.
- I chose to keep all modules in the main SFS (I didn't move them to a zdrv).
- I chose the icelandic.jpg wallpaper, the Gradient-grey GTK theme, the Gradient-grey JWM theme and the Stardust icon theme.
- I chose to keep the white text and black shadows.
- I chose to keep all the "modules.*" files.
- I chose to skip stripping.
- I chose to skip the burning of the ISO.
- I chose to build the devx module.
Everything in this stage is pretty much self-explanatory.
The end result is a complete Puppy ISO and the matching devx module (if you chose to generate it) in the sandbox4 directory (inside the Woof directory). The ISO can be used as any other Puppy ISO. You can run the ./3builddistro script again, with different options, after getting familiar with it.
That's it.
Enjoy