File layout

From CunningPlans

[edit] "cgi-bin" directory

A "cgi-bin" directory is a directory that is pointed to by a ScriptAlias directive in the Apache web server configuration, or by equivalent statements in other web servers. Anything in this directory that is marked as an executable file (using the Unix "chmod" command) is run as a program, just as if it was launched from the command line.

The web server configuration will associate a virtual path (like "/bin" or "/scripts") with a physical path on the filesystem, like "/var/www/example.com/cgi-bin".

It is in this physical directory (or a subdirectory) that you must install baldrick-stub, the loader and "main() function" provider for Baldrick. When the program begins running, its current working directory is this CGI directory. Other paths used by the program are all relevant to this directory:

• "lib", where Perl modules (Baldrick and your application) are loaded from
• "etc", where config files are found

" "templates", where templates for generating output to the user are found.

[edit] "lib" directory

Baldrick consists of a set of Perl modules in the Baldrick:: namespace.

Baldrick Modules that you write, or that you download from other authors, will also have a set of Perl modules, with a different namespace prefix (i.e., AcmeShopCart:: or JimsBlog::).

Though Baldrick could be installed system-wide by unpacking it into the standard Perl include path (/usr/lib/perl5 and such), this is not always possible or desirable. On a shared server hosting multiple sites, you may not have permission to install anything there; or you might wish to maintain separate installations of Baldrick for multiple web sites on the same server. Thus, I recommend you maintain a private installation within your web site's ServerRoot or cgi-bin directories.

baldrick-stub, by default, assumes that there is a "lib" directory within cgi-bin, and it adds this "lib" directory to the Perl include-path using this statement:

   use lib 'lib';

If you wish to specify another "lib" directory, edit baldrick-stub and change this line:

   use lib '/var/www/mysite.com/lib';
   use lib '/home/george/lib';

In this "lib" directory - whether within cgi-bin or elsewhere - the Baldrick libraries are placed within a "Baldrick" subdirectory. (The Perl loader expects to find them there because of the Baldrick:: class prefix). There is also a Baldrick.pm file at the top level of "lib" - the one Baldrick perl file without the Baldrick:: module prefix.

Modules that you write or that you download should be in their own namespaces, also within this "lib" directory, but not within the "lib/Baldrick" subdirectory or the "Baldrick::" namespace.

A sample layout:

  lib/
  lib/Baldrick.pm                       # Alternate entry point.
  lib/Baldrick/App.pm
  lib/Baldrick/Baldrick.pm              # loader class -- 'use Baldrick::Baldrick'.
  lib/Baldrick/Dogsbody.pm
  lib/Baldrick/[...many other *.pm files...]

  lib/MyApp/                            # A Module.
  lib/MyApp/MyAppDogsbody.pm            # its main entry point
  
  lib/FredsBlog/
  lib/FredsBlog/...many .pm files...