Current location

narf Source control manager Git

path: root/README
diff options
authorNick Daly <>2012-07-04 12:36:37 -0500
committerNick Daly <>2012-07-04 12:36:37 -0500
commit8e165905185486a67b1efb59c94ac50d01d76bb5 (patch)
treedb8ea43debf1ee1e9273e781db134da7bc9f61d2 /README
parent79bc67d22f44d21db4ff8f4381f00b922b9a0a8b (diff)
Updated the documentation, added hacking instructions.
Diffstat (limited to 'README')
1 files changed, 60 insertions, 4 deletions
diff --git a/README b/README
index ff24788..3fa0571 100644
--- a/README
+++ b/README
@@ -10,8 +10,7 @@ copy the stick contents to the internal 2gb microSD card.
*** understand what they're going to do before you run them...
-Install required build packages:
- apt-get install multistrap qemu-user-static u-boot-tools git hg
+# To Use It
Partition a USB stick to have a small FAT partition and large ext2 partition,
create a /media/freedom mount point, and add entries to /etc/fstab like:
@@ -73,10 +72,67 @@ time-consuming attempts to boot grom gigE, which makes boot go much faster:
-- - - - -
+# To Understand It
Be aware that this is a *very* imcomplete solution for now, suitable only
for developers .. you will want to at least do things like create unique
ssh host keys for your device!
-- - - - -
+Digging into the code should be fairly straightforward. There are only six
+files you need to be aware of:
+- /Makefile: The makefile that describes and builds the system.
+- /mk_dreamplug_rootfs: Builds the DreamPlug's root file-system.
+- /bin/projects: The place for external projects to hook into and customize
+ themselves before they're copied to the image.
+- /bin/finalize: Finalizes and prepares the build for booting.
+- /source: The root file system.
+- /source/ Pre-boot configuration that needs to be run on the device
+ itself (from within a chroot).
+## Makefile
+There are three major targets to be aware of:
+- dreamstick: The default target. This loads an image to a USB drive that can
+ be used to install the FreedomBox without opening up your DreamPlug and
+ voiding the warranty. You'll need a JTAG, though.
+- weekly-card: The target used to produce the weekly FreedomBox test release.
+ This will copy the image to a card that can be popped directly into the
+ microSD card slot in the DreamPlug. The DreamPlug will boot happily without
+ needing a JTAG.
+- stamp-dreamplug-rootfs: The root file system itself. It doesn't get installed
+ anywhere (that's done by the other two targets), but is a good way to test
+ whether the image will actually build, without waiting for all that pesky
+ hardware I/O.
+## mk_dreamplug_rootfs
+Starts building the system by creating all the destination directories and
+installing the base system.
+## /bin/projects
+Where projects that want to integrate into the FreedomBox should hook into.
+Keep in mind, we aren't in a chroot at this point. The only environment
+variables you'll probably need are:
+- user: The non-root user's name (uid = 1000).
+- homedir: The non-root user's home-directory.
+## /bin/finalize
+Getting the system ready for boot, doing the things that don't need to be done
+inside a chroot. You probably don't need to change this.
+## /source
+The root file system on the DreamPlug. Modify this, and you're modifying what
+ends up on the FreedomBox.
+## /source/
+This is executed from a chroot during the build process to do configuration that
+needs to be done on the device itself. You shouldn't need to modify this. If
+you're installing a project that needs to change how the system configures
+itself, you're probably doing something wrong.