A Brief Guide to Hacking on the positron source code
----------------------------------------------------

IMPORTANT DIRECTORIES

* positron/ - The positron modules
* scripts/  - The positron program itself
* test/     - Various scripts and data files for testing


ENVIRONMENT

Use the scripts/env.sh to set your environment variables such that
Python uses the files stored in the positron source tree rather than
files already installed to your system.  In bash, do:

. scripts/env.sh [toplevel directory of positron source]

So on my system, I do:

. scripts/env.sh /home/stan/xiph/positron

Note that this sets the path so you can type "positron" and it will
run the version in the source tree.


TESTING

You can test positron without a real Neuros attached to your computer.
To do this, go to the test/ directory and unzip neuros_root.zip.  This
file contains a complete image of an empty Neuros.  You can tell
positron to use this directory as the mount point.  For example, if
you unzip neuros_root.zip in the test/ directory, and test/ is your
current working directory, then you can do things like:

positron -m neuros_root list
positron -m neuros_root sync

Assuming you have neuros_root on a hard disk larger than 2 GB,
positron will assume the device is a 20 GB hard disk configuration of
the Neuros.  To simulate the 128 MB flash memory model, you have to
go through a few more steps.

1. Create a disk image for your fake flash device:

dd if=/dev/zero of=flash_neuros.img bs=1024 count=131072

2. Format the disk image with the FAT filesystem:

/sbin/mkfs.vfat flash_neuros.img

3. Make a mount point for the disk image.

mkdir flash

4. Mount this disk image (as the root user) with the proper
   permissions:

mount -t vfat -o loop,umask=0 flash_neuros.img flash

5. Switch back to a normal user and unzip the sample Neuros files:

unzip neuros_root.zip

6. Copy the files to the disk image:

cp -r neuros_root/* flash/

You can safely ignore errors about setting permissions.  This is just
because FAT filesystems don't have file permissions.

Now you can use positron with this mount point:

positron -m flash sync
positron -m flash list

etc.


TESTING MUSIC FILE DETECTION

The test/ directory also contains a script for exercising the
positron.audiofile module's detect method.  It assumes you have one or
more directories of test files with extensions such that:
    *  .mp3 for all MP3 files
    *  .ogg for all Ogg Vorbis files
    *  something else (or no extension) for everything else

To run it, type:

./detect_test.py [dir1 dir2 ... dirN]

It will output some stats about the testing, and a list of files that
failed.