Computing: Free Pascal Programming

Programming Home   Home   Contact

Creating command line programs with Lazarus.

Command line programs (i.e. programs, running in the Windos "DOS box" or in a Linux console) may appear to meanstream computer users as dinosaurs, that were necessary at the beginning of the PC age, but that aren't useful in any way today. Advanced users or specialists in domains as for example bioinformatics, however, know, that there are lots of situations, where a graphical interface is not needed, where a given task may run withot any user intervention, similar as batch programs on a mainframe, taking its input data from the command line or a file and producing an output on the console or to a file. On Unix systems, lots of administration is done by using shell scripts or text-based Perl programs. As an example of a simple command line program on Windows, have a look at my tutorial about Web development environment setup on MS Windows: 5. Perl, where I describe a tool, written in Free Pascal, that copies the Perl or PHP file actually edited within Komodo Edit, from my development library to the webserver and then starts the webbrowser, pointed to the URL of the script; in other words, a command line program, that allows to test CGI scripts from within Komodo Edit.
There is no fundmental difference between creating a graphical application and a command line program: In Lazarus, choose New > Program (instaed of "New > Application"). However, there are 2 points to consider, when creating a command line program:
  • When writing from a Free Pascal program to Windows Command Prompt, the output on the screen will not be with UTF8 encoding. As a result, non-ANSI characters ("non-English letters") will be displayed as some "garbage", the character(s) actually displayed depending on the actual Windows system codepage.
  • Console programs often need command line parameters and sometimes the actual or special environment variables. Getting their value may easily be done, using the ParamCount and ParamStr resp. the GetEnv functions, but how to proceed to test a command line program, that needs parameters, directly from within Lazarus?
UTF8 display in Windows Command Prompt.
As I said above, writing from a Free Pascal program to Windows Command Prompt, without considering the UTF8 issue, results in a senseless display of non-ANSI characters. As an example, a screenshot of my "3-month multi-lingual calendar", where the accentuated characters and umlauts are displayed as one or two symbols, that depend on the Windows system codepage.
Incorrect UTF8 display in Windows Command Prompt
In the original version of the program, I used "e" instead of all "e with accent", and "ae", "oe" and "ue" instead of the umlauts. Just a work-around, not a solution. I searched the Free Pascal Wiki and was astonished to discover, that the UTF8 issue may be fixed, without having to do any codepage conversions or other function calls, but simply by including the LazUTF8 unit in the program. In fact, with this unit included, all is handled by Lazarus itself: With every call to the Write procedure, Lazarus converts the text to be displayed from UTF8 to the Windows system codepage (and "é" and "ä" will automatically be displayed correctly).
Unfortunately, this is not the whole story. In fact, it only works for the characters, that are actually part of the Windows system code page. For most applications, this shouldn't be a problem. However, if you need a whole set of special characters (such as a foreign language alphabet), things become lots more complicated; for help on what possibilities you have in this case, please, search the Free Pascal Wiki or "UTF8 in Windows Command Prompt" related articles.
Including the LazUTF8 unit, by simply addíng it to the "uses" statement, is not enough, however. Building my calendar program, aborted with a "Unit not found" error message!
Compilation abortion due to LazUTF8 unit not found
As a Linux operating system or a Perl distribution, the Lazarus development environment is based on packages. These are "collections" of units, depending on a given package, i.e. units, that are only available if Lazarus knows, that that package is required to build an application or program. The error message, we got before, tells us that the LazUtils package is a requirement to use the LazUTF8 unit. This package, automatically added to the project, when creating a GUI application, is missing for a command line program. To add it, choose Project > Project Inspector in the Lazarus menu bar, then in the "Project Inspector" window, select New requirement.
Lazarus Project Inspector: Adding a new requirement
The "New requirement" window opens, and you get an impressive list of packages, by default shipped with Lazarus, or, maybe, packages, that you found somewhere on the Internet and installed them yourself. Some of them are globally used with GUI applications (such as LCL), others are specific for specific applications. In the list, choose LazUtils and push the OK button.
Adding the LazUtils package to a command line program
With the LazUtils package requirement added, rebuild the command line program: Success!
Successful build of a UTF8 command line program
And finally, rerunning the calendar program: Mäerz, Abrëll, MÉ, DË ... all characters are now displayed correctly.
Correct UTF8 display in Windows Command Prompt
Testing console programs with command line parameters.
Testing console programs with command line parameters is not really a problem. First, you can build your program and then run it from Command Prompt with the actual parameters. Second, you can fill the command line variables by adding assignments during the test phase. The first of these procedures has the disadvantage that you have to switch to Command Prompt each time you want to run the program. The second one allows you to stay within Lazarus, but the code, concerning the reading of the command line parameters, will not be tested. Having a possibility to directly telling Lazarus to run a program with given command line parameters would be conveniant. And, of course, this possibility exists.
In the Lazarus menu bar, choose Run > Run Parameters.
Specifying command line parameters in Lazarus [1]
The "Run Parameters" window opens and you can specify your actual command line parameters in the Command line parameters field, just in the way, you would do it at the command line. Note, that in this window, you can set several other options such as starting your program from another program, setting an output display (Linux only) or defining a working directory (useful in particular if your program uses files, stored in a given directory).
Specifying command line parameters in Lazarus [2]
Testing console programs with given environment variables.
Environment variables are special operating system variables, that contain information about the OS itself, about the actual user and her private directories, about the paths to be searched for executables and the one corresponding to "Program Files" and "Program Files (x86)", in a similar way as on a webserver, there are environment variables, containing information about the server and website access. Sometimes, it is necessary to read these variables, what may be done using the GetEnv function, included in the DOS unit. There are also cases, where you want to run your program with environment variables different from those set on your system. As examples, testing a program, that takes different actions depending on the platform (32bit or 64bit) or a program that uses data from a private library (with the need of knowing the computer user name).
No need to change your actual environment variables. Just tell Lazarus to run your program with the environment variables, you want to test. To do this, choose Run > Run Parameters as before and set your test environment variables in the Environment tab, by adding them to the User overrides section.
Specifying testing environment variables in Lazarus