positron/HACKING

   1 A Brief Guide to Hacking on the positron source code
   2 ----------------------------------------------------
   3
   4 IMPORTANT DIRECTORIES
   5
   6 * positron/ - The positron modules
   7 * scripts/  - The positron program itself
   8 * test/     - Various scripts and data files for testing
   9
  10
  11 ENVIRONMENT
  12
  13 Use the scripts/env.sh to set your environment variables such that
  14 Python uses the files stored in the positron source tree rather than
  15 files already installed to your system.  In bash, do:
  16
  17 . scripts/env.sh [toplevel directory of positron source]
  18
  19 So on my system, I do:
  20
  21 . scripts/env.sh /home/stan/xiph/positron
  22
  23 Note that this sets the path so you can type "positron" and it will
  24 run the version in the source tree.
  25
  26
  27 TESTING
  28
  29 You can test positron without a real Neuros attached to your computer.
  30 To do this, go to the test/ directory and unzip neuros_root.zip.  This
  31 file contains a complete image of an empty Neuros.  You can tell
  32 positron to use this directory as the mount point.  For example, if
  33 you unzip neuros_root.zip in the test/ directory, and test/ is your
  34 current working directory, then you can do things like:
  35
  36 positron -m neuros_root list
  37 positron -m neuros_root sync
  38
  39 Assuming you have neuros_root on a hard disk larger than 2 GB,
  40 positron will assume the device is a 20 GB hard disk configuration of
  41 the Neuros.  To simulate the 128 MB flash memory model, you have to
  42 go through a few more steps.
  43
  44 1. Create a disk image for your fake flash device:
  45
  46 dd if=/dev/zero of=flash_neuros.img bs=1024 count=131072
  47
  48 2. Format the disk image with the FAT filesystem:
  49
  50 /sbin/mkfs.vfat flash_neuros.img
  51
  52 3. Make a mount point for the disk image.
  53
  54 mkdir flash
  55
  56 4. Mount this disk image (as the root user) with the proper
  57    permissions:
  58
  59 mount -t vfat -o loop,umask=0 flash_neuros.img flash
  60
  61 5. Switch back to a normal user and unzip the sample Neuros files:
  62
  63 unzip neuros_root.zip
  64
  65 6. Copy the files to the disk image:
  66
  67 cp -r neuros_root/* flash/
  68
  69 You can safely ignore errors about setting permissions.  This is just
  70 because FAT filesystems don't have file permissions.
  71
  72 Now you can use positron with this mount point:
  73
  74 positron -m flash sync
  75 positron -m flash list
  76
  77 etc.
  78
  79
  80 TESTING MUSIC FILE DETECTION
  81
  82 The test/ directory also contains a script for exercising the
  83 positron.audiofile module's detect method.  It assumes you have one or
  84 more directories of test files with extensions such that:
  85     *  .mp3 for all MP3 files
  86     *  .ogg for all Ogg Vorbis files
  87     *  something else (or no extension) for everything else
  88
  89 To run it, type:
  90
  91 ./detect_test.py [dir1 dir2 ... dirN]
  92
  93 It will output some stats about the testing, and a list of files that
  94 failed.