Next Previous Contents

1. Foreword and Introduction

1.1 Copyright

Copyright (c) 2000,2001,2002,2003 Carlo Strozzi.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

You should have received a copy of the GNU Free Documentation License along with this work; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

1.2 Preface

A word of caution is in order: this document is still in an early stage of its development. It may not be very well structured, nor very clear, neither easy to follow. It represents only a first attempt at providing some documentation on the software project that it describes. The document may undergo extensive rewriting and restructuring in the future, and it may take time before it becomes a really useful Programming Guide.

This working draft describes, and provides instructions for the use of, CSA, a small application development environment for the World-Wide Web.

CSA tends to be biased in favour of Linux. This means that, wherever it matters, CSA makes use of the GNU versions of the various UNIX commands, as those are the ones that are usually packaged together with the Linux O.S. And among the many Linux "distributions" available nowadays, CSA has been developed entirely on Debian, although it should run just as fine on any other common Linux distributions. CSA is Free Software, released under the terms of the GNU General Public License. As such, it fully qualifies as Open Source Software.

For a thorough understanding of this paper you need to have a good knowledge of the UNIX/Linux Programming Environment, that is the shell and the main Shell Utilities, like sed, grep, find, etc. Some basic familiarity with the C language won't hurt either. The utilities to which I refer to in the rest of this document are the GNU incarnations of such tools, with the exception of the AWK language interpreter, of great importance to CSA, for which I'm using Mike Brennan's mawk. Wherever I talk about AWK in the rest of the document I will usually mean mawk, unless otherwise specified. It is definitely required that the reader has a good knowledge of the rc shell, a rather minimal scripting language which syntax is half-way between the C shell and the Bourne shell. Of course it is necessary to know the technology the World Wide Web is built upon, and in particular how the CGI (Common Gateway Interface) works.

Most important, to really grasp the CSA philosopy I definitely recommend that you read the resources listed in the bibliography.

1.3 Conventions used

In the text that follows, prescriptive rules are identified by upper-case adverbs like "SHOULD", "SHOULD NOT", "MUST" and "MUST NOT", while descriptive adverbs are left in lower-case.

1.4 Introduction

"Why Unix commands, CGI and the Shell ?". This is probably the first question one would ask. The short answer might be: "because I like them" :-)

A lengthier explanation is that I like simple and effective things; it may sound old-fashioned to talk about CGI and shell scripts in these days of Java, C# and SOAP, but in spite of all the hype that has developed around those novelties, I have so far yet to see something that they do, that cannot be done with a simpler, cheaper and more traditional approach like the classical shell+utilities UNIX cornerstone. The shell and its countless utilities are very effective, readily available and well-understood tools, and because of they widspread usage they are usually more robust and properly debugged than newer environments. But probably the most important benefit is that you can re-use your system-administration knowledge to build fairly complex Web applications, without having to learn "the new hot programming language of the day". After all, this general approach is typical of the UNIX programming environment: getting the most from existing components by making them work together, leveraging on what others have built and thus maximizing productivity. Finally, many useful applications either still lack, or will never provide, the possibility to be accessed over the Web, either through a human-targeted HTML interface or as an application-oriented Web Service. With a bit of shell glue, this can be overcome, and a stand-alone system can thus become part of a larger, Web-based distributed application. It is like providing the original appliance with a Web socket, where others can tap into through the usual and well-understood CGI Application Programming Interface.

Many times, in the past, I have found myself scripting for the Web with the shell and its utilities. Unfortunately, everytime I also had to write ad-hoc code around my scripts, to deal with reading, decoding and validating CGI input, providing answers in the form of HTML pages, error-checking and reporting, logging, and the countless other ancillary services that every Web programmer knows well about. CSA was built out of the frustration from having to re-write most of those parts upon any new application that I had to design. Neither I wanted to resort to other "big tools" for Web development, that disregard the shell and that are not built with "The UNIX Philosophy" in mind.

1.5 Bug reports

There is a mailing list for discussions related to CSA. The address is csa-devel(at)strozzi.it. To subscribe simply send a message to minimalist(at)strozzi.it with the word "subscribe" (without the quotes) in the message subject.

Please send bug reports (fixes are most welcome) to the same list csa-devel(at)strozzi.it. Always include as much information as possible, especially the content of file csa.version, which is created in the CSA installation directory during install. By 'bug reports' I mean not just errors in the code, but also grammatical mistakes, typos and bad English constructions in the documentation, as English isn't my native language.


Next Previous Contents