.\" $HeadURL$ $LastChangedRevision$ .\" .TH ADEINTRO 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN" .ne 5 .SH NAME adeintro \- An introduction to ADE .br .ne 5 .SH DESCRIPTION This page provides an introduction to version ADE_APP_TOKEN_RELEASE_ID of Alexis's Development Environment (ADE). .PP ADE is an unintegrated development environment for Unix-like operating systems. It is primarily for shell and Perl programs. Its components may be used in concert for rapid prototyping (see .B MODULE DEVELOPMENT CYCLE below), or individually, hopefully spawning new uses for these tools (see .B NON-DEVELOPMENT USES OF ADE below). .SH MODULE DEVELOPMENT CYCLE Typically people do not just write programs, but also write documentation, and perhaps a test suite. We refer to these components collectively as a module. .PP Module development usually starts with a creation phase, continues with many iterations of a development phase, maybe then a testing phase and a release phase. At this point the cycle forks: the developers return to doing development, and the release itself, now in the hands of your customers, enters its installation phase. .PP These phases and their assorted sub-phases and .B ADE\fR's possible part in them are described below. .TP 25 .B Creation Creating a module is normally done from scratch or by cloning an old module and then editing it. .IP "" 25 ADE provides template modules written in .B sh\fR(1) and .B perl\fR(1). The command .B adegmt\fR(1) can be used to retrieve one of these and make appropriate substitutions (where the module mentions its own name). .IP "" 25 These template modules do nothing. Manual pages are included, which document this behaviour. Also included are other miscellaneous standard documentation files (README.1ST, INSTALL, COPYING, etc.) and a regression test suite, which checks the very limited functionality of these programs; all tests pass. .TP .B Development - editing ADE does not provide an editor; there are enough wheels around to obviate their reinvention. .TP .B Development - libraries While the core functionality of the program must be written by you, ADE provides libraries (see .B adelib\fR(UNDOCUMENTED)), which provide standard interfaces and behaviours for the template modules' languages for the following areas of functionality: .RS 25 .TP 20 .B messaging for internal errors, normal errors, warnings, verbose information messages and debug messages .TP .B lock file management for the creation (with stale checks) and removal of lock files .TP .B tmp file management to ensure that temporary files are removed, whether your program exits correctly or is interrupted .TP .B init/exit control for more information, see .B Anatomy of an ADE-based program\fR, below. .RE .TP .B Development - Makefiles ADE provides includable Makefiles to specify many standard compile- and install-time recipes. .TP .B Development - build configuration Build configuration files, which specify what is to be installed where, need to exist even in the development environment. These are created using .B adeconf\fR(1). Alternatively, an includable Makefile can invoke it, so that the user only need invoke .B make\fR(1). Alternatively you can do the path management in any other way you see fit. .TP .B Development - compilation If a script uses libraries, then it may load them at runtime or at install-time. ADE uses the second alternative in the belief that this results in a more resilient product. (See .B Why compile scripts? below.) ADE provides .B adespp\fR(1) as compiler, or more strictly, as pre-processor. .IP "" 25 Of course this does not mean that you .I have to compile your scripts; the ADE libraries are on the system in a readily determinable location (see .B aderoot\fR(1)), so they could equally well be loaded at runtime. .TP .B Development - archiving ADE does not provide a version control system. However ADE libraries can convert RCS and SVN identification strings to version information, for reporting at runtime, and the releaser program, .B aderel\fR(1), will ignore .B RCS and .B .svn directories. .TP .B Testing ADE includes a test harness .B adetest\fR(1) and a set of standard tests, which an ADE-based program should attempt to pass. .TP .B Release - bundling Making a release typically involves some last-minute changes to some text strings (e.g. release number), and the creation of a suitably named and structured .B tar\fR(1) file. ADE provides .B aderel\fR(1) to do this (not to the original sources, of course). .TP .B Installation - configuring the build The person installing an ADE-based program will need to configure the building of the program in exactly the same way as the developer had to. This step is normally done when the user executes the GNU .B configure\fR(UNDOCUMENTED), program, which the developer had to include in the release file. In the .B ADE world, the program to do this step is already on the customer's system. .TP .B Installation - compiling To compile an ADE-based program, libraries and tools for compilation and installation are required. ADE provides this. ADE is therefore a prerequisite for any ADE-based programs. (See .B Offloading install-time prerequisites below.) .IP "" 25 The person installing an ADE-based program will need to compile the program in exactly the same way as the developer had to (or did not have to). .TP .B Installation - testing The person installing an ADE-based program may want to test the build in exactly the same way as the developer did. .TP .B Installation - installing Many software packages (e.g. GNU software) do not rely on a decent .B install\fR(1) program being on the target system, and provide one as part of their own distribution. ADE-based software is free to use .B adeinst\fR(1), which is certain to be available on the target system (see .B IDEAS BEHIND ADE below). .SH IDEAS BEHIND ADE .SS Why compile scripts? Loading libraries at runtime has the advantages that it requires less effort by the developer and installer, and that libraries may be upgraded independently of the programs which use them. .PP But loading the libraries at runtime requires more effort by the user: it is the user who is more likely to see conflicts between libraries and programs, when the libraries are upgraded or even moved or deleted by someone unaware of their dependencies. .PP In an ideal world, in which all installed software is packaged with explicitly encoded dependencies and prerequisites, these problems should not arise. In practice, particularly in the system administration domain where scripting is the prevalent form of programming, they do arise. The main reasons are consequent to the main advantages of scripting: (i) scripts are often used to rapidly development tools to fulfil requirements which are thought to be short-term and therefore not worth packaging but later become permanent components of a system, (ii) because of a scripting language's relatively high level, making scripts portable is generally a much faster operation that making a C program portable, so scripts migrate rapidly to other operating systems with differing package formats (e.g. RPM on Redhat Linux, deb on Debian, depot on HP-UX, pkg on Solaris); packaging then becomes a major overhead. .PP To avoid this problem, ADE-based programs are pre-processed to include their libraries (rather like static linking) at compile-time. This ensures that if the libraries are upgraded, moved or deleted, the program will still function correctly. .PP Certain programs and directory paths may be mentioned in more than one file in a program's sources. These files may not even be written in the same language (think about a program which loads a configuration file, and its man page which states where the default configuration file is located). This causes a headache for developers because when the location changes (when you program evolves out of your home directory, when local filesystem rearrangements require it, when your program no longer loads one configuration file, but now a directory full of them, etc), there are many changes to make, and possibly some to forget to make. .PP This problem can be solved by exploiting preprocessing further. ADE-based programs and man pages (and any other file in the source distribution you want) load these program and directory path definitions from a single file. .SS Offloading install-time prerequisites First let us consider the different kinds of dependencies a program can have. Consider this program written in shell: .IP .nf .fam C #!/bin/sh echo "hello world" .fam T .fi .PP It has no compile-time dependencies. It has no install-time dependencies - besides the operating system's native .B cp\fR(1) command. It has no runtime dependencies - besides the operating system's native .B sh\fR(1) command. .PP Now consider this C program: .IP .nf .fam C main() { printf("hello world\en"); } .fam T .fi .PP It has a compile-time dependency on an ANSI C compiler. As with the shell script, it has no real install-time dependencies. It may have a runtime dependency on libc. .PP Now consider this C program: .IP .nf .fam C #include #include XtAppContext context; XmStringCharSet char_set=XmSTRING_DEFAULT_CHARSET; main(argc, argv) int argc; char *argv[]; { Widget toplevel, label; XmString S; toplevel = XtAppInitialize(&context,"",NULL,0,&argc,argv,NULL, NULL,0); label = XmCreateLabel(toplevel,"label",NULL,0); S = XmStringCreateLtoR("hello world", char_set); XtVaSetValues(label, XmNlabelString, S, NULL); XtRealizeWidget(toplevel); XtAppMainLoop(context); } .fam T .fi .PP It has more compile-time dependencies on libraries than I dare think about. There are no real install-time dependencies. There are run-time dependencies on the libraries. .PP Finally think about a normal GNU program: it may have some compile-time dependency on libraries. It has a compile-time dependency on a path configurator program, and probably also depends on .B gcc\fR(1). It has an install-time dependency on a powerful install tool. These last two are interesting because they are delivered with the GNU program itself! In the former case because no such tool exists in the target environment, and in the latter because the availability and suitability of such a command varies from operating system to operating system to the extent where the safest thing is for the GNU program to provide it itself. .PP Given that prerequisite libraries are common, why not sneak in the other dependencies at the same time; they can lie dormant on the target system until a customer installs a program and then - because to install this program at all certain prerequisites had to be met - the developer is assured that it will be possible to to configure paths, compile programs and install them without the necessity for him to deliver them, or cater for all possibilities on the unknown target system. .PP The overhead to the user is minimal; they had to install the libraries anyway. The saving to the developer is enormous. .SS Anatomy of a ADE-based program Please refer to the template modules, which can be retrieved with .B adegmt\fR(1). .br .ne 5 .SH NON-DEVELOPMENT USES OF ADE .B Adespp\fR(1) can be used to combine text files and then extract parts of them later. The principal use of this is to combine site variant configuration files into one single file. For example, the configuration file for my favourite window manager FVWM contains: .IP .nf .fam C .B PipeRead "adespp .fvwm2rc.spp -" .fam T .fi .PP and then in .fvwm2rc.spp I put paragraphs such as this: .IP .nf .fam C .B #spp if [ `domainname` = homenet ] .B +\ \ \ \ \ \ \ \(dqGames ...\(dq\ \ \ \ \ Popup games-menu .B #spp else .B +\ \ \ \ \ \ \ \(dqRlogin ...\(dq\ \ \ \ Popup remote-hosts-menu .B #spp fi .B +\ \ \ \ \ \ \ \(dqBrowser\(dq\ \ \ \ \ \ \ Exec netscape & .fam T .fi .PP In this way, the configuration files are the same in the two different locations that use it. .br .ne 5 .SH EXAMPLES The following commands will create a Perl program called \(oqfoo', compile it, test it, install the programs in ~/bin, the man pages in ~/man and discard the rest, and finally - assuming the PATH is set up correctly, request the program to display its usage information: .IP .nf .fam C .B adegmt -L perl foo .B cd foo .B make config ADECONF_FLAGS="--prefix=/tmp/deleteme --bindir=$HOME/bin \(rs .B \ \ \ \ --mandir=$HOME/man" .B make .B make tests .B make install .B foo --help Usage: foo [ ] Options: -V | --version display program version -v | --verbose verbose -d | --debug= set debug level -h | --help display this text -p | --list-paths list paths used by this program .fam T .fi .br .ne 5 .SH CAVEATS .B ADE\fR's shell and Perl libraries are not documented yet. In the mean time please look at template modules. .br .ne 5 .SH SEE ALSO adegmt(1), adeconf(1), adespp(1), aderoot(1), adetest(1), adeinst(1), aderel(1), sh(1), perl(1), make(1), tar(1), install(1), cp(1), gcc(1), lex(1), bison(1), cpp(1) .br Subversion project homepage (http://subversion.tigris.org) .br RCS project homepage (http://www.cs.purdue.edu/homes/trinkle/RCS/) .ne 5 .SH AUTHOR ADE_APP_TOKEN_AUTHOR_NAME .br .ne 5 .SH COPYRIGHT & DISTRIBUTION POLICY Copyright (C) 1995-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME .PP This program 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. .PP This program 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. .PP You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.