Console Mode Pascal: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Console-Mode Pascal Programming
2	2
3	3		Many of us were writing [[Pascal]] [[Program\|programs]] long before [[Graphical User Interface\|Graphical User Interfaces]] (GUIs) and [[IDE\|Integrated Development Environments (IDEs)]] became fashionable. Many others are beginners at Pascal programming and need to be able to try out the basic tools of the language. Still others need to write [[Command-line interface\|console]]- or [[Text User Interface\|text-mode]] applications in order to perform complex system control tasks.
4	4
5	5		### Console mode programming without Lazarus
6	6
7	7		Even though many prefer to use the [[Lazarus IDE]] to write console mode programs, you can also write them with any text editor and compile them yourself by calling the [[FPC]] [[Compiler\|compiler]], e.g. this for a program in example.pas:
8	8
9	9		``` bash
10	10		fpc example.pas
11	11		```
12	12
13	13		Also, the text mode fp IDE (looks a bit like old [[Turbo Pascal]]) is available. In the next sections we will focus on programming with [[Lazarus]].
14	14
15	15		### Console mode programming with Lazarus
16	16
17	17		Lazarus provides an ideal environment for learning Pascal, and for developing text-mode programs. All the functionality of the Integrated Development Environment can be used, including the Source Editor with its [[Syntax highlighting\|syntax highlighting]], access to the libraries, complex searching and code completion tools, and syntax checking. If you do not want a [[TForm\|Form]] with its visual components, you do not need one, but the Lazarus Source Editor is still a great environment for program development. You can compile and run your program during development, without ever leaving the Editor.
18	18
19	19		To start a console-mode program, go to the Main Menu and select Project -\> New Project and then select either Program or Console Application. The IDE will not generate all the extra files associated with a full graphic application, and will not open an Object Inspector box, but will open the Source Editor with a skeleton program structure and await your programming input.
20	20
21	21		> Note: Under Windows a GUI application has no console and thus can not writeln or readln. You will get File not open errors. Disable under Project Options / Compiler Options / Linking / Target specific options / Win32 GUI application to create a console application. In Lazarus IDE 1.4, this is under Project(menu) / Project Options / Compiler Options / Config and Target / Target specific options / Win32 GUI application.
22	22
23	23		> Note: Lazarus has some functionality for command line programs, such as [[CopyFile\|copyfile]]. To use these, add a project requirement for LazUtils, which will not pull in the entire LCL. Then add the relevant unit to your uses clause.
24	24
25	25		#### Project type: Console Application
26	26
27	27		Selecting this project type in Lazarus creates a program with a new class derived from TCustomApplication. TCustomApplication provides a lot of the common things and makes programming command line utilities easy. For example checking command line options, writing help, checking [[Command line parameters and environment variables\|environment variables]] and [[Exceptions\|exception]] handling. All [[LCL]] programs use this automatically.
28	28
29	29		#### Project type: Program
30	30
31	31		As a demonstration, we will write a very minimalistic Pascal program. In the IDE, select the 'Program' project type and let the IDE helps you a bit. For example when you add another [[Unit\|unit]] the IDE will automatically add the unitname to the program [[Uses\|uses]] section. This behavior is defined in the project options. So you can go between 'Program' and 'Custom Program' at any time.
32	32
33	33		An example for complete beginners:
34	34
35	35		``` Pascal
36	36		program Project1;
37	37		{$mode objfpc}{$H+}
38	38		uses
39	39		{$IFDEF UNIX}{$IFDEF UseCThreads}
40	40		cthreads,
41	41		{$ENDIF}{$ENDIF}
42	42		Classes;
43	43		begin
44	44		WriteLn('Hello World!');
45	45		ReadLn;
46	46		end.
47	47		```
48	48
49	49		### Pascal scripts
50	50
51	51		Additionally, it is possible to write scripts that are dynamically compiled by [[InstantFPC]], a cross-platform solution to run (small) Pascal programs as scripts. The shebang
52	52
53	53		#!/usr/bin/env instantfpc
54	54
55	55		permits to start the script like a stand-alone program.
56	56
57	57		> Note: Though it is used to run Pascal scripts, InstantFPC uses regular Object Pascal, not the PascalScript script language. So "PascalScript" and Pascal script are not the same.
58	58
59	59		## Running a Program
60	60
61	61		#### Compile
62	62
63	63		When you have finished your program (or program fragment) you can compile and run it by selecting Run -\> Build (or Quick Compile) from the Main Menu or clicking on the Green (Run) triangle symbol ![](/wiki-images/b/b8/Start.png) in the Button Bar. Any compiler messages (warnings, progress reports or error messages) will appear in the Message Box, and hopefully there will eventually be a message to say
64	64
65	65		'Project "Project1" successfully built.:)'.
66	66
67	67		But where is the program??!!
68	68
69	69		If you have not yet saved the program, then the IDE put it into the temporary directory (e.g. /tmp under linux, C:\temp under windows, see Environment Options / Files / Directory for building test projects).
70	70
71	71		If you already saved the project, then the program was created in the same directory, where you saved the project1.lpi file.
72	72
73	73		#### Run in Console
74	74
75	75		You can execute the program by going to a console (terminal) window, then use cd to change to the directory and typing the name of the program. On Unix/Linux, if it is in the current directory you will have to start with ./ as the program will probably not be found in the PATH.
76	76
77	77		Example for Linux/Unix where a program is stored in /tmp:
78	78
79	79		``` bash
80	80		cd /tmp
81	81		./Project1
82	82		```
83	83
84	84		However, it can be very inconvenient to keep skipping out of the Lazarus Editor and into a terminal window and back again. Fortunately, there is a mechanism that allows a terminal window to be opened from within the Lazarus environment.
85	85
86	86		#### Run in IDE
87	87
88	88		In internal console: show in the terminal output window.
89	89
90	90		In redirect output.
91	91
92	92		From the Main Menu, select Run -\> Run Parameters, then check the box for "Use launching application". The first time you do this and try the Compile/Run sequence, you will probably get a rude message saying:
93	93
94		-	~~`"xterm: Can't execvp /usr/share/lazarus//tools/runwait.sh: Permission denied". `~~
	94	+	```text
	95	+	"xterm: Can't execvp /usr/share/lazarus//tools/runwait.sh: Permission denied".
	96	+	```
95	97
96	98		If this happens, you need to change the permissions on the appropriate file (for example using chmod +x filename, or using the Windows utility for changing permissions); you might have to do this as root. After this, each time you launch your program, a console box will appear and all your text I/O (readln, writeln etc) will appear in it.
97	99
98	100		After your program has finished execution, a message "Press enter" appears on the screen. Thus any output your program generated will remain on the screen until you have had a chance to read it; after you press 'enter' the console window closes.
99	101
100	102		On Linux, if the above message "xterm: Can't execvp /usr/share/lazarus//tools/runwait.sh: Permission denied" does not appear after checking the box for "Use launching application", type `/usr/bin/xterm $(TargetCmdLine)` and check `Use launching application` (xterm is installed on almost all Linux systems).
101	103
102	104		Unfortunately, this method does not allow you to use the integrated debugger.
103	105
104	106		#### Run in IDE with redirected output
105	107
106	108		If you want to see what is written to stdout and want to use the integrated debugger as well, stdout can be redirected to a file with the following code:
107	109
108	110		``` Pascal
109	111		uses
110	112		baseunix;
111	113
112	114		var
113	115		OutputFile: text;
114	116
115	117		begin
116	118		Assign(OutputFile, 'Output.txt');
117	119		if FileExists(Filename) then begin
118	120		Append(OutputFile);
119	121		end
120	122		else begin
121	123		Rewrite(OutputFile); { open file for writing, destroying contents, if any }
122	124		end;
123	125
124	126		ResultCode := fpdup(OutputFile, output);
125	127
126	128		if ResultCode < 0 then begin
127	129		raise Exception.CreateFmt('dup failed: %s', [ResultCode]);
128	130		end;
129	131		Close(OutputFile);
130	132		end.
131	133		```
132	134
133	135		Output.txt can then be viewed with 'tail -f output.txt' or viewed with an editor if 'tail' is not available on your [[Operating System\|os]].
134	136
135	137		Alternatively, using Lazarus 0.9.31 or up (on Linux only): In the "View" menu, under "Debug Windows" there is an entry for a "console output" to view stdout
136	138
137	139		## Unicode (UTF8) output
138	140
139	141		If you want your console mode program to show Unicode ([[UTF-8\|UTF8]]) output on Windows Vista and higher (and perhaps on earlier versions, too), you can use the SetConsoleOutputCP command to set the console to the UTF8 character set.
140	142
141	143		> Note: you will need to make sure the font of the console can show the letters you want to output (e.g. Greek, Cyrillic, Korean).
142	144
143	145		> Note: you will need to include the Windows unit.
144	146
145	147		See [[LCL Unicode Support]] for more details on Unicode support in Lazarus and FPC.
146	148
147	149		Example program:
148	150
149	151		``` Pascal
150	152		program uniconsole;
151	153
152	154		{$mode objfpc}{$H+}
153	155		{$APPTYPE CONSOLE}
154	156
155	157		uses
156	158		{$IFDEF UNIX}
157	159		{$IFDEF UseCThreads}
158	160		cthreads,
159	161		{$ENDIF}
160	162		{Widestring manager needed for widestring support}
161	163		cwstring,
162	164		{$ENDIF}
163	165		{$IFDEF WINDOWS}
164	166		Windows, {for setconsoleoutputcp}
165	167		{$ENDIF}
166	168		Classes
167	169		;
168	170
169	171		var
170	172		UTF8TestString: string;
171	173
172	174		begin
173	175		{$IFDEF WINDOWS}
174	176		SetConsoleOutputCP(CP_UTF8);
175	177		{$ENDIF}
176	178		UTF8TestString:= 'rosé, водка and ούζο';
177	179		writeln ('plain: ' + UTF8TestString);
178	180		{Apparently we do not need UTF8ToConsole for this
179	181		UTF8ToConsole did not do anything for me in fact.}
180	182		end.
181	183		```
182	184
183	185		## Examples
184	186
185	187		You can use the Lazarus editor to try out all the examples in the standard Pascal textbooks, or you can write your own. Some of the most useful procedures are those for executing system commands or for running other programs (whether written in Pascal, C or Perl, or shell or batch scripts).
186	188
187	189		#### Execute shell command
188	190
189	191		Here is an example for a Custom Program or Program... that is Linux/Unix/macOS specific though:
190	192
191	193		``` Pascal
192	194		program TryShell;
193	195		uses
194	196		Classes, Unix;
195	197		var
196	198		S: LongInt;
197	199		begin
198	200		S := fpsystem('/bin/ls -la .p'); //lists .pp, .pas, .php, .png etc in current directory
199	201		WriteLn('Program exited with status : ', S)
200	202		end.
201	203		```
202	204
203	205		#### Example: update FPC and Lazarus
204	206
205	207		Rather more complex commands can be executed. For example, if you have already checked out the SVN repositories for FPC and Lazarus (see [[buildfaq]]) you could keep your FPC and Lazarus source files up-to-date by retrieval from the SVN repository with the following sequence of calls:
206	208
207	209		``` Pascal
208	210		program LazUpdate;
209	211		uses
210	212		Classes, Unix;
211	213		var
212	214		S: LongInt;
213	215		begin
214	216		S := fpsystem('cd /usr/local/src/fpc/devel/fpc ; make clean');
215	217		S := fpsystem('cd /usr/local/src/fpc/devel/lazarus ; make clean');
216	218		S := fpsystem('cd /usr/local/src/fpc/devel ; svn update fpc >& ~/cvscheckout.log');
217	219		S := fpsystem('cd /usr/local/src/fpc/devel ; svn update lazarus >& ~/cvslaz.log' );
218	220		end.
219	221		```
220	222
221	223		Note that issuing the command
222	224
223	225		``` Pascal
224	226		fpsystem('cd /somedirectory');
225	227		```
226	228
227	229		followed by
228	230
229	231		``` Pascal
230	232		fpsystem ('do something in that subdirectory');
231	233		```
232	234
233	235		does not work, because after each fpsystem() [[Function\|function]] call the execution of the program returns to the directory it started in; so we need to include multiple statements per line within our calls to shell via fpsystem(). \[Rather: it always starts in . \]
234	236
235	237		One does not have to enter every command as a separate line of Pascal; one could create a bash script file like this (from [[buildfaq]]):
236	238
237	239		``` bash
238	240		#!/bin/sh
239	241		cd /usr/local/src/fpc/devel
240	242		cd fpc
241	243		make clean
242	244		cd ..
243	245		cd lazarus
244	246		make clean
245	247		cd ..
246	248		svn up fpc >& ~/cvscheckout.log
247	249		svn up lazarus >& ~/cvslaz.log
248	250		```
249	251
250	252		Name it updatelaz.sh, and then instead of using bash to execute it directly, call it from a Pascal program thus:
251	253
252	254		``` Pascal
253	255		(* This can be compiled or used as a Pascal script *)
254	256		program LazUpdate1;
255	257		uses
256	258		Classes, Unix;
257	259		var
258	260		S: LongInt;
259	261		begin
260	262		S := fpsystem('updatelaz.sh')
261	263		end.
262	264		```
263	265
264	266		## See also
265	267
266	268		- [[Command line parameters and environment variables]]
267	269		- [[Executing External Programs]]
268	270		- [[Debugger Console App\|Debugging console applications]]
269	271		- [[InstantFPC]]
270	272
271	273		---
272	274		From the Free Pascal wiki, page "Console Mode Pascal", as it stood on 2023-05-02 after a change by Thierrybo, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history