This documentation is meant to describe the files and directories that make up AmphetaDesk, either in source form or as a runtime. It's intended as a means to find out what that stupid file over there means, or whether this file over here should be included with a distribution. With the new design in v0.93+, most of the files in the source code are now shipped with the distributed runtime's regardless.
There are four different places where a file could be: "Source" means it's only relevant in the source code, "Runtime" means it should be distributed along with any compiled package, "Both" assumes the file shows up in the runtime and source, and "-" means that the file is not required in a distribution (although it won't hurt if it's there).
| File/Directory | Location | Description |
|---|---|---|
| /AmphetaDesk
/AmphetaDesk.app /AmphetaDesk.exe | Runtime | These are the runtime files built from AmphetaDesk.pl as per our
build instructions. These files have all the necessary libraries and
XS code, as well as the Perl interpreter. The .exe is the
Win32 runtime, the .app is the OS X runtime, and the other
is the Classic Mac runtime (the XS code under Classic is loaded from the
shared libs directory). |
| /AmphetaDesk.log | - | The actual logfile from either the source or runtime versions of AmphetaDesk. If this file doesn't exist, then it is automatically created. Each time AmphetaDesk is run, it will overwrite the old logfile if it's larger than a certain limit and start afresh. If something weird's happening with AmphetaDesk, there's a good chance we can find out why by looking in here. |
| /AmphetaDesk.pl | Both | The wrapper code that loads our true code from the lib directory. This file should be kept as simplistic as possible - it really serves only as a launching pad for our compilation. |
| /README.txt | Both | This is just a simple and quick README file that instructs the user how to install AmphetaDesk on Windows, Macintosh, and Linux machines. A duplicate copy exists in the docs directory. Other README.txt files are spread out through the other directories, and serve as quick introductions to the files within. |
| File/Directory | Location | Description |
| /data/myChannels.opml | - | This file is created when the user first runs AmphetaDesk and contains a default set of shipped channels. As the user customizes their AmphetaDesk, this file is continually updated. Deleting this file will cause the default channels to be loaded again. |
| /data/mySettings.xml | - | mySettings.xml defines all of the user's
preferences, hopes, and dreams. If this file is missing, AmphetaDesk
will use default entries, else the entries within this file override them. |
| /data/channels/* | - | This directory holds all of the saved data and metadata from the channel feeds. The contents are always changing (whether it be new channels being added, or old files being deleted). |
| /data/internal/version.txt | - | The version.txt file is used to check whether
the currently running AmphetaDesk is the latest version available. Each
time AmphetaDesk is run, we check this file against the remote
version.txt
to see if any changes has occurred. If so, we display the contents of the
file in the AmphetaDesk window. |
| /data/lists/services-channels-recent.xml | - Both | This is referenced whenever people click to "Add A Channel". It's a slimmed down version of the complete list available from Syndic8.com, removing all sites that haven't been updated within the 15 days. This file does not need to be distributed with the runtime because it will be downloaded if it doesn't exist, but it does make the user's initial loading of AmphetaDesk a bit longer (and more confusing), so we're currently recommending against it. |
| File/Directory | Location | Description |
| /docs/* | - Both | This is the directory where the file you're currently reading is stored. This directory is not required in distributed runtimes (as all the template links point to the disobey.com site), but at the moment, it'd be insane NOT to include it. The files in this directory won't be explained, since they're not crucial to the running of AmphetaDesk (you can gain a good enough idea by looking at the Documentation Index of AmphetaDesk). |
| File/Directory | Location | Description |
| /extras/amphetadesk.rc | - | By James A. Pattie, this is an rc.d/init.d
script to start/stop/restart the AmphetaDesk daemon (assuming it's under
/usr/local/amphetadesk, though this is easily modifiable). It has
been tested and verified with chkconfig on a Redhat system. |
| /extras/createpods.pl | - | This script creates HTML versions of all the AmphetaDesk POD documentation contained within the modules of the lib directory. All created output is stored in docs. |
| File/Directory | Location | Description |
| /lib/AmphetaDesk.pm | Both | This Perl module is the "router" of AmphetaDesk, setting up the runtime environment, starting the internal webserver and GUI, and processing all incoming requests off to their respective modules. It loads all the other modules from the lib directory. |
| /lib/AmphetaDesk/Channels.pm
/lib/AmphetaDesk/ChannelsList.pm /lib/AmphetaDesk/MyChannels.pm |
Both | The three modules that do most of the work for
AmphetaDesk. Channels.pm controls the parsing, download and
storage of our syndicated files, ChannelsList.pm covers the
display of the OPML export of Syndic8.com,
and MyChannels.pm manipulates the user's subscription list. |
| /lib/AmphetaDesk/OS/Linux.pm
/lib/AmphetaDesk/OS/MacOS.pm /lib/AmphetaDesk/OS/MacOSX.pm /lib/AmphetaDesk/OS/Windows.pm |
Both | These four files handle the OS specific portions of AmphetaDesk - they control GUI routines, API handlers for the browsers, and other things that can change from OS to OS. Which file to use is determined at runtime. |
| /lib/AmphetaDesk/Settings.pm | Both | Settings.pm handles the creation
and manipulation of mySettings.xml,
and also contains the default settings. |
| /lib/AmphetaDesk/Templates.pm | Both | A glorified wrapper around the Text::Template module, and handles the parsing of all the templates used to create the browser-based GUI. |
| /lib/AmphetaDesk/Utilities.pm | Both | Routines not related to anything else, such as whitespace cleaning, logfile output, character encodings, and message storage. It's full of generic routines for everyone's use. Yum. |
| /lib/AmphetaDesk/Versioning.pm | Both | This module currently doesn't do much - it merely downloads a version.txt file and compares the version number within to the locally running copy. In future versions of AmphetaDesk, it'll automatically download and update to newer versions. |
| /lib/AmphetaDesk/WebServer.pm | Both | Merely a subclass of HTTP::Daemon, the sole purpose of this routine is to tweak our internal webserver's identification. Fickle. This module also emulates Radio Userland. |
| /lib/AmphetaDesk/WWW.pm | Both | Most of the routines within this file are wrappers around various LWP::UserAgent functions, thus this module concerns itself with access to the web - downloading, reading headers, etc. |
| /lib/Text/* /lib/XML/* |
Both | CPAN accessible code relating to our template processing and XML parsing. For more information on these modules, see the Text::Template and XML::Simple documentation. |
| File/Directory | Location | Description |
| /shared libs/*
/lib/shared libs/* |
Runtime (Mac) | This directory and its contents ONLY exist on a compiled Classic Macintosh runtime and is necessary for proper operation. It contains various C/XS libraries compiled for use. |
| File/Directory | Location | Description |
| /templates/*
/templates/gui/* |
Both | You can find detailed descriptions of all these files in the template/skinning portion of the documentation. They control the AmphetaDesk look and feel of the webpages, and the gui subdirectory controls the icons and logos of the runtime. |