PSP Help Doc Indexer System

1. Introduction
2. License
3. History
4. Compilation & Hosting
5. Configuration File
6. Modules:
   1. Base64Enc
   2. FileShare
   3. GZIP
   4. Hostname
   5. HTTP
   6. MD5Crypt
   7. RegExp
   8. SDS
   9. SMTP
   10. Substrings
   11. URLEnc
   12. Web
7. FAQ
8. Links
9. Credits

Compilation and Hosting

Choosing web hosting for your PSP site

1. Operating System, Webserver and Shell.

   Supported operating systems are: Windows, Linux, FreeBSD, NetBSD, OpenBSD and Solaris. Supported and tested web servers are: Apache, Apache2. We don't advise you to choose Windows hosting for 2 reasons. First is that most of Windows hosts have IIS+ASP web programming platform when PSP is designed for Apache. And the second one is security. Although on Windows you don't need to care about rights (permissions) for directories and files, Windows systems are absolutely unprotected from binary CGIs. For example, there's no way to forbid binary CGIs to use WinAPI calls in httpd.conf. So cgi-bin on Windows may mean Perl, but not binary CGI. Windows hosting is also usually more expensive and less available. So try to avoid using Windows hosting (except for those cases when you have control of the server, or server admin is god-like).

   UNIX-like systems are better choice. When choosing between several UNIX systems pay attention to shell access and your local OSes. If you have shell access and possibility of installing latest FPC version for your account, this hosting suits you even better. However, this is not required. Compiling on the server also means you will be putting load on the server, so you can also find some advantages in not using or having access to shell access. Basically, when choosing web hosting, you only need to check that the server you will be on can run Apache and supports binaries in cgi-bin. Almost all hosting companies out there use Apache and support CGI-BIN.

   If you have no shell account then you'll have to compile the applications on your local machine. But you can still compile your linux PSP applications on your MS Windows computer, so it is not a big deal. Choosing hosting with an OS which you have installed is nice, but is not required (i.e. you can compile something on Debian and still run it on RedHat server with no problems). Installing new OS to another partition, running it in emulators (e.g. CoLinux) or virtual machines (e.g. Virtual PC), cross-compilation in FPC, and a cross compiler capable IDE's will solve many of your dilemmas.

   Don't forget about processors: if you compile your app on 32-bit x86 processor and try to run it on 64-bit Opteron or RISC processor, this attempt will fail. However, this is generally not an issue because plenty of hosting companies run the popular x86 (AMD, Intel, etc.) processor.

   Three key points are:

   1. preferably UNIX-like OS,
   2. Apache web server
   3. binary CGI-BIN support (not just perl cgi).

   Optional, not required: shell access.

   If giving short and complete advice: choose Linux hosting with CGI-BIN. Hosting is not a big problem, as probably 90 percent of economical hosts out there offer this. There are even a few free hosts and plenty of under $5/month hosts who support CGI-BIN.

2. Database.

   Of course, databases are not always needed. For example, you don't need any database server when using SDS. But big complex projects require more powerful database solutions. Database support requirement depends on database used in your project. But MySQL support is not a minus for the hosting, of course.

3. SSH, SSL.

   As mentioned above, SSH is a big plus, but is really optional. As for SSL it depends on your needs. If you need secure HTTP connection support for your site you need SSL or shared SSL. If not, you don't need it. From the PSP side, there's no difference between HTTP and HTTPS.

4. Space, Domains, Crontabs, etc., etc., etc....

   Depending on your project and your requests.

Compilation, Debugging and Testing.

FPC

1. Putting files. There are 2 ways of putting PSP units. First is your FPC units path. In this case you just copy all PSP units in that folder and then you stop worrying about missing unit files. But I don't advise this way for version conflicts reason. So I advise you to put PSP units you use to your project directory. In this case you see what units are used for compilations.
2. Compiler settings. Recommended FPC configuration options. I'll describe how it looks from FP-IDE. In console configuration or Lazarus you may configure it by analogy with this description. First enter Options -> Compiler. In Syntax tab switch on following options: Object Pascal support, Allow LABEL and GOTO and Delphi compatibility. Other options for your taste. In Code generation tab switch on all the runtime checks. So you'll spend more time debugging, but your programs will be protected from stack, heap and arithmetic overflows. Choose target processor, switch on optimizations. If choosing between size and speed I usually choose speed. But it is up to you. In Verbose tab switch on Warnings and Hints when debugging, but switch them off when doing release compilations.
3. Using compiler. In FP-IDE, Lazarus and other IDEs everything is intuitive. In console mode or via SSH you do it like this:

   cd ~/project_folder
   fpc -B source_file.pp
   

   -B option means rebuilding all used units. It takes more time but it is necessary when applying changes in units.

Debugging and Releasing

1. Debugging tips. When debugging you need as much information about runtime program behavior as possible. FPC is great for debugging because it has a lot of integrated debugging utilities. I won't describe usage of GNU GDB here, I just tell about debugging with FPC. So, in your FPC Options switch the Mode to Debug and then enter Debugger options. Choose Generate also backtrace line information. With this option you will get huge executables, but when program crashes with any runtime error it will trace the error route and it will even tell the line of your source file on which the error occured. It is lots of saved time. And don't forget about classical debugging tips: step by step debugging and debug output. Also when debugging web applications on a web server your program may crash before having sent headers. In this case "500: Internal Server Error" will occur. Having received this message you may do several things: try testing unstable code in non-server environment, try using debug output file or just force sending headers on program start, so you can see the backtrace info.
2. Releasing tips. When your program is debugged finally you should care about Release optimization. It means the least executable size and the top executable speed. I won't give code optimization lessons, I just tell about release FPC configuration. Enter Options. Switch compiler Mode to Release. Then in Debugger configuration enable Strip all debug symbols from executable and Skip debugger information generation. What else? Don't forget about executable packers such as UPX.

Testing on Webserver

Cross-Compiling

1. Cross-compilation. FPC supports cross-comiling rather well. Cross-compiling is useful when you need only to compile some crossplatform code for target platform, without need of setting up a webserver and testing on it. For example, if you're running Windows for development and if you have a UNIX hosting for testing, cross-compiling will allow you to compile binaries for target UNIX OS, so you can upload them on server.
2. Obtaining necessary files. Besides your crossplatform code (such as PSP) and FPC2 for the system you're running you'll need files specific for cross-compilation. First you need FPC units for target platform. You can get them from SourceForge. If there are no specific units packages you can download whole package (for example, fpc-2.x.x.i386-linux.tar.gz). Also you need crossplatform binary utility which is located on ftp://ftp.freepascal.org/mirrors/fpc/contrib/cross/ or ftp://ftp.freepascal.org/pub/fpc/contrib/cross/. If you're running Windows, the best choice is ftp://ftp.freepascal.org/mirrors/fpc/contrib/cross/mingw/win32crossbinutils2005.zip (or ftp://ftp.freepascal.org/pub/fpc/contrib/cross/mingw/win32crossbinutils2005.zip) which contains crossplatform binaries for different target platforms.
3. Putting files. After you have obtained the files, you should put them somewhere. Unpack your FPC target files to some temprorary directory and then find precompiled units folder in it (e.g. /lib/fpc/2.x.x/units/i386-linux) and copy it into your FPC units directory (e.g. C:\FPC\units). Then copy target binutils (e.g. i386-linux-ar.exe, i386-linux-as.exe, i386-linux-ld.exe and the rest files from the same folder) into your FPC bin directory (e.g. C:\FPC\bin\i386-win32). Make a backup copy of original ar, as and ld and then replace them with those cross-compilation variants (you'll have to rename them back when you return to normal compilation). OK, now you're ready to compile.
4. Compiling. As I'm describing use of crossplatform fp-ide here, I will describe cross-compiling from fp ide also. So, open your source file, then go to Compile. Choose Target platform (notice that you can hardly comile a program for SPARC processor when you have i386). And then click Compile or Build as you usually do. If everyting is OK, you'll get binaries for the target platform. You can also cross-compile from console mode, where -T compiler switch stands for target platform defination.
5. PSP. I've described general crosscompilation with FPC. But there is still one unsolved problem that makes PSP crosscompiling impossible: dynamic linking is not supported by crossplatform ld.exe, and as PSP relies on GNU libc on UNIX, crosscompilation of PSP programs fails. We hope this will be fixed soon.

PSP IDE

1. LazarusRB. One of the PSP-related projects which are being developed is LazarusRB with PSP plug-ins. It will help you develop webpages in less clicks, in a more visual way, along with cliptext tools and more.
2. FakeLinux. It is also in development. FakeLinux will let you develop for Linux directly from MS Windows. It works like coLinux service running Linux instance in Windows process. This Linux distro has preinstalled Apache, FPC and a special connector daemon that talks to the IDE. How does it look like from a user side? You work on your PSP project in Lazarus with your local folders like normal. It synchronizes your Windows folder with a folder on coLinux system. You can compile for Linux directly from the IDE. Then you can test your application with Apache running on the same coLinux system, using your Windows browser. Then you just put the compiled files on your hosting server via FTP through either the Lazarus FTP plug-in or your favorite FTP program.