Files and Directories

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/DirectoryLocationDescription
/AmphetaDesk
/AmphetaDesk.app
/AmphetaDesk.exe
RuntimeThese 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 BothThe 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 BothThis 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/DirectoryLocationDescription
/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/DirectoryLocationDescription
/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/DirectoryLocationDescription
/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/DirectoryLocationDescription
/lib/AmphetaDesk.pm BothThis 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
BothThe 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
BothThese 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 BothSettings.pm handles the creation and manipulation of mySettings.xml, and also contains the default settings.
/lib/AmphetaDesk/Templates.pm BothA 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 BothRoutines 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 BothThis 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 BothMerely 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 BothMost 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/*
BothCPAN 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/DirectoryLocationDescription
/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/DirectoryLocationDescription
/templates/*
/templates/gui/*
BothYou 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.