LUFDOC : setuputils

Notes

The setup required includes having a compiler installed, downloading the Powtils/PSP package from sourceforge, and setting up your search paths and config files.

There are no config files that need to be uploaded to the server for 1.6.1 and greater versions.

Download Powtils

The latest copy of Powtils is here.

Setting up compiler

Install a compiler such as freepascal. At current time of writing, developers are using 2.0.4 and 2.2.0 or the latest version on the freepascal website. Freepascal (FPC) is a professional grade compiler suitable for business or personal software development.

We've made IFDEF's so the units can compile with Kylix or Delphi, and we have tested some units on Turbo Delphi and Delphi 5. However we may have forgotten IFDEF's in some units in the latest releases. PasForum contains a post that explains how to get the utilities running on Turbo Delphi. FPC can create web programs that run on Linux, BSD, and Windows servers. The FPC compiler is extremely compatible with Delphi, almost word for word in version 2.0.0 and above.

Remote Compilation

In the future, this setup guide will contain instructions on how to install fpwserv and fpw, which are programs that allow any Microsoft Windows or Apple/Mac user to remotely create unix apps on any typical web server.

Editor or IDE

Try MSEIDE, EditPlus, Lazarus, Delphi, FP-IDE, or others.

Setting Up Paths

If you are compiling with FPC command line compiler, or using a text editor with ppc386.exe, then you should create a fpc.cfg file and add the -Fu and -Fi search paths in that file. An example of some fpc.cfg files may be loacated in the /examples/ section of your Powtils/PSP download. The examples directory uses relative paths, searching for units in for example ../../main/ and ../../main/inc/ when you compile with pwumain.pas.

Unpack the files from your download to a directory structure similar to:

Windows:
  C:\powtils\1.6.0.2\

Unix:
  /home/me/powtils/1.6.0.2/

Or:
  /usr/local/powtils/1.6.0.2/

The sub directories are laid out in the zip file for you: just unpack to a directory of your choice, such as in C:\powtils\ on windows as shown above, or such as in /home/yourself/ on unix.

If you are compiling with an IDE dedicated to FPC or Delphi, add the search paths to your configuration dialog window or project options. An example of some search paths to use on Windows and Unix:

-FuC:\powtils\1.6.0.2\main\
-FuC:\powtils\1.6.0.2\version\
-FiC:\powtils\1.6.0.2\main\inc\
-FuC:\powtils\1.6.0.2\main\inc\zlib\
-FuC:\powtils\1.6.0.2\extras\*\

-Fu/home/me/powtils/1.6.0.2/main/
-Fi/home/me/powtils/1.6.0.2/main/inc/
-Fi/home/me/powtils/1.6.0.2/version/
-Fu/home/me/powtils/1.6.0.2/main/zlib/
-Fu/home/me/powtils/1.6.0.2/extras/*/

The -Fu directive tells the freepascal compiler to search for units in those paths. With Delphi or with a freepascal IDE, you can simply add the above search paths into your dialog window.

Preserving existing fpc.cfg file

IMPORTANT: If you are using the command line, you probably want to preserve your main existing fpc.cfg file by including it first, like so:

#INCLUDE /etc/fpc.cfg
-Fu  unit path here...
-Fi  include path here...

On Windows, it would be something such as:

#INCLUDE c:\pp\2.0.4\bin\i386-win32\fpc.cfg
-Fu  unit path here...
-Fi  include path here...

This include directive tells the fpc command line compiler to first include your original fpc config file that shipped with the compiler, and then it processes the rest of your config file below that directive.

Setting up your local server

For local testing of web programs you can download Apache which is free, or use the server installed on your operating system. Powtils work on almost any webserver that supports CGI-BIN, however we mainly test on Apache.

For testing unix applications on a Windows computer, consider VirtualBox, CoLinux, and VMWare.

Setting up your live server

CGI programs produced with Powtils are compatible with all sorts of web hosts such as your typical CPANEL/PLESK, BSD, Linux, or MS Windows hosting provider.

There is no installation of the Powtils required other than uploading a config file your CGI program directory. The config file is called pwu_win.conf or pwu_unix.conf file and a copy of example config files are included with your Powtils Download.

If you have disabled the CFG_ON define in versions 1.6.1 and above, then the config file does not need to be uploaded. It is currently disabled by default. You can also see that other options are available for you to enable such as SESS_ON, DBUG_ON, and more.

Upload Web Application

Simply upload your compiled CGI program to the server, in /cgi-bin/. If you have no cgi-bin folder, create one in your public html.

On unix servers, change the permissions so that the program is executable (usually 755, 767, or 777 depending on your server). You may need to change permissions on the cgi-bin directory itself, if you created one.

On Windows servers, make sure cgi-bin is enabled for executables.. as some servers limit cgi-bin to perl scripts only.

Optional DLL/DSO

If you use dynpwu.pas you must upload the pwu-1.6.x.x.dll or dso library to the server. The library path is specified on line one in your configuration file. The config file library path one line one can contain a $DOCROOT macro which is your public html document root directory.. but this macro will not work unless the web program is invoked from a web server (i.e. command line testing of the CGI will not invoke the web server, therefore $DOCROOT macro won't work on a console launch of the program).