Homec4science
Diffusion invenio-infoscience (maint-1.2) Browse

R3600/modules/webhelp/web/hacking/directory.html.wml
374a590462c7maint-1.2

Last Change
Raw File

directory.html.wml
View Options

## $Id$
## This file is part of the CERN Document Server Software (CDSware).
## Copyright (C) 2002, 2003, 2004, 2005 CERN.
##
## The CDSware is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2 of the
## License, or (at your option) any later version.
##
## The CDSware is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with CDSware; if not, write to the Free Software Foundation, Inc.,
## 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
#include "cdspage.wml" \
title="Directory Organization" \
navbar_name="hacking-directory-organization" \
navtrail_previous_links="<a class=navtrail href=<WEBURL>/hacking/>Hacking CDSware</a> " \
navbar_select="hacking-directory-organization"
<p>Version <: print generate_pretty_revision_date_string('$Id$'); :>
<pre>
Please find some notes below on how the source (as well as the target)
directory structure is organized, where the sources get installed to,
and how the visible URLs are organized.
1. CDSware will generally install into two directories, taken from
--with-prefix and --with-webdir configuration variables. These
are discussed in points 2 and 3 below, respectively.
2. The first directory (--with-prefix) specifies general CDSware
install directory, where we'll put CLI binaries, Python and PHP
libraries, manpages, log and cache directories for the running
installation, and any other dirs as needed. They will all live
under one common hood.
For example, configure --with-prefix=/usr/local/cdsware-DEMODEV,
and you'll obtain the following principal directories:
/usr/local/cdsware-DEMODEV/
/usr/local/cdsware-DEMODEV/bin
/usr/local/cdsware-DEMODEV/lib
/usr/local/cdsware-DEMODEV/lib/php
/usr/local/cdsware-DEMODEV/lib/python
/usr/local/cdsware-DEMODEV/lib/wml
/usr/local/cdsware-DEMODEV/var
/usr/local/cdsware-DEMODEV/var/cache
/usr/local/cdsware-DEMODEV/var/log
with the obvious meaning:
- bin : for command-line executable binaries and scripts
- lib/php : for our own PHP libraries, see below
- lib/python : for our own Python libraries, see below
- lib/wml : for our own WML libraries, see below
- var : for installation-specific runtime stuff
- var/log : for all sorts of runtime logging, e.g. search.log
- var/cache : for all sorts of runtime caching, e.g. OAI
retention harvesting, collection cache, etc
This scheme copies to some extent the usual Unix filesystem
convention, so it may be easily expanded later according to our
future needs.
3. The second directory (--with-webdir) should be located under Apache
htdocs tree and specifies where to put the Web scripts (PHP,
mod_python), HTML documents and images, and so on. This is where
webuser-seen files are located. Basically, the files there contain
only the interface to the functionality that is provided by the
libraries stored under the library directory.
The WEBDIR directory is further structured according to whom it
provides services. We distinguish user-level, admin-level and
hacker-level access to the site, as reflected by the visible URL
structure.
a) The user-level access point is provided by the main WEBURL
address and its subdirs. All the user-level documentation is
available under WEBURL/help/. The module-specific user-level
documentation is available under WEBURL/help/&lt;module&gt;/.
b) The admin-level access is provided by WEBURL/admin/ entry
point. The admin-level documentation is accessible from the
same place. The admin-level module-specific functionality and
help is available under WEBURL/admin/&lt;module&gt;/. (If
it's written in mod_python, it usually points to
WEBURL/&lt;module&gt;admin.py/ since we configure the server to
have all mod_python scripts under the WEBDIR root directory.)
c) The hacker-level documentation is provided by WEBURL/hacking/
entry point. There is no hacker-level functionality possible
via Web, of course, so that unlike admin-level entry point,
the hacker-level entry point provides only a common access to
available hacking documention, etc. The module-specific
information is available under WEBURL/hacking/&lt;module&gt;/.
4. Let's now return a bit more closely to the role Python and PHP
library directories outside of the Apache tree:
/usr/local/cdsware-DEMODEV/lib/php
/usr/local/cdsware-DEMODEV/lib/python
Here we put not only (a) libraries that may be reused across
CDSware modules, but also (b) all the "core" functionality of
CDSware that is not directly callable by the end users. The
"callable" functionality is put under "webdir" in case of web
scripts and documents, and under "bindir" in case of CLI
executables.
As for (a), for example in the PHP cdsware library you'll find
currently the common PHP error handling code that is shared between
BibFormat and WebSubmit; in the Python cdsware library (in fact,
cdsware Pythonic 'module', but we are reserving the word 'module'
to denote 'CDSware module' in this text) you'll find config.py
containing WML-supplied site parameters, dbquery.py containing DB
persistent query module, or webpage.py with templates and functions
to produce mod_python web pages with common look and feel. These
could and should be reused across all our modules. Note that I
created only a small number of "broad" libraries at the moment. In
case we want to reuse more code parts, we'd refactor the code more,
as needed.
As for (b), for example the existing search engine was split into
search.py that only contains three "callable" functions, which goes
into WEBDIR, while the search engine itself is composed of
search_engine.py and search_engine_config.py living under LIBDIR.
In this way we can easily create "real" CLI search, that will
depend only on the search libraries in LIBDIR, and that will get
installed into BINDIR.
To recap:
- For each CDSware module, I'm differentiating between
"callable" and "core" parts. The former go into WEBDIR or
BINDIR, the latter into LIBDIR.
- Our PHP/Pythonic libraries contain several sorts of thing:
- the implementation of the "callable" functions
- non-callable internal "core" or "library" code parts, as
stated above. Not shared across CDSware modules.
- utility code meant for reuse across CDSware modules, such
as dbquery.py
- Pythonic config files out of user-supplied WML (non-MySQL)
configuration parameters (see
e.g. search_engine_config.py)
5. The same strategy is reflected in the organization of source
directories inside CDSware CVS. Each CDSware module lives in a
separate directory located under "modules" directory of the
sources. Further on, each module contains usually several
subdirectories that reflect the above-mentioned packaging choice.
For example, in case of WebSearch you'll find:
./modules/websearch
./modules/websearch/bin
./modules/websearch/doc
./modules/websearch/doc/hacking
./modules/websearch/doc/admin
./modules/websearch/lib
./modules/websearch/web
./modules/websearch/web/admin
with the following straightforward meaning:
- bin : for callable CLI binaries and scripts
- doc : for documentation. The user-level documentation is
located in this directory. The admin-level
documentation is located in the "admin" subdir. The
programmer-level documentation is located in the
"hacking" subdir.
- lib : for uncallable "core" functionality, see the comments
above
- web : for callable web scripts and pages. The user- and
admin- level is separated similarly as in the "doc"
directory (see above).
The structure is respected throughout all the CDSware modules, a
notable exception being the MiscUtil module that contains subdirs
like "sql" (for the table creating/dropping SQL commands, etc) or
"demo" (for creation of Atlantis Institute of Science, our demo
site.)
- end of file -
</pre>
c4science · Help