Hi all

attached is a rough draft of a FAQ. Will add about the Solaris 8 binaries. Any additions, corrections, comments?

Thanks Russ russwhit@mind.net *********************************************************************

GNU Pascal Frequently-Asked Questions List, Edition 0.5, February 2000 by Russ Whitaker russwhit@mind.net

based on GNU Pascal Frequently-Asked Questions List, Edition 0.4, for GPC version 2.0, November 1996 by J.J. van der Heijden j.j.vanderheijden@student.utwente.nl

For up-to-date information, ask the GPC mailing list (see below).

Index ***** 1.0 GNU Pascal - what, where and why 2.0 Installation 3.0 Pascal and system libraries 4.0 Strings 5.0 Pascal on the djgpp platform 6.0 Getting Help 7.0 Miscellaneous

1.0 GNU Pascal ***************

1.1 What and why? =================

The purpose of the GNU Pascal project is to produce a Pascal compiler (called GNU Pascal or GPC) which

* combines the clarity of Pascal with powerful tools suitable for real-life programming,

* supports both the Pascal standard and the Extended Pascal standard as defined by ISO, ANSI and IEEE. (ISO 7185:1990, ISO/IEC 10206:1991, ANSI/IEEE 770X3.160-1989)

* supports other Pascal standards (UCSD Pascal, Borland Pascal, Pascal-SC) in so far as this serves the goal of clarity and usability,

* may be distributed under GNU license conditions

* can generate code and run on any computer for which the GNU C compiler can generate code and run.

Pascal was originally designed for teaching. GNU Pascal provides a smooth way to proceed to challenging programming tasks without learning a completely different language.

1.2 What is the current version? ================================

The latest release as of this writing is GPC-19991030. GPC requires GCC as a back-end. Patches for GCC 2.8.1 thru GCC 2.95.2 are provided but it is recommended that you use at least GCC 2.95.

1.3 Where can I get it? =======================

You can download the latest alpha or beta releases of gpc from

ftp://agnes.dida.physik.uni-essen.de/

Is it compatible with Turbo Pascal (R) ? ========================================

GPC is currently *not* a drop-in replacement for Borland's Turbo Pascal (R). It supports a number, but not all of the Borland extensions to the Pascal language. There is no replacement for most of the Borland runtime library functions. GNU Pascal is part of the GNU project, so portability is one of its primary goals. For this reason, non-portable features of Borland Pascal will probably not be included into GNU Pascal. More information can be found in the section "Borland Pascal" of the GPC manual. Also see "About Strings", below.

2.0 Installation related questions **********************************

This section discusses some common problems with the installation of GNU Pascal.

Which platforms are supported by GNU Pascal? ============================================

GPC uses the GCC backend, so it should run on any system that is supported by GNU CC. This includes a large variety of Unix systems, MS-DOS, OS/2 and Win32. A full list of platforms supported by GCC can be found in the file `INSTALL' of the GCC distribution. Not all of these have actually been tested, but it is known to run on these platforms:

ix86-linux (Linux 2.x, ELF) i486-linuxaout i486-linuxoldld i386-freebsd1.2.0 djgpp V2 (msdos) emx 0.9B (OS/2, msdos) cygwin32 beta16 (Windows95, Windows NT) mips-sgi-irix5.3 sun-sparc-sunos4.1.4

...

...

Ok people - send us your success stories, with canonical machine

name! <<<

Which components do I need to compile Pascal source code? =========================================================

A complete Pascal compiler system should at least have:

1. The actual compiler, GPC. While there are some binaries available you can build GPC yourself. You nee a working C compiler, some tools: bash, ar, patch, make, the GCC source, and the GPC source.

2. An editor, Assembler, linker, librarian and friends.

3. A C library. If you have a working C compiler you already have this.

4. A debugger, if you want to debug your programs.

For most people, the GNU binutils and GNU debugger (gdb) are a good choice, although some may prefer to use vendor specific tools.

How do I build a GPC compiler? ==============================

If you have a typical ix86 box the routine is fairly simple. Any other computer you should carefully read the documentation in GCC*/install.

Assuming you have: 1. A working C compiler. 2. The usual tools: ar, awk, bash, bison, ld, make, patch, sed 3. The GPC and GCC tar.gz source in directory /usr/local/src Then here's a cookbook recipe:

1. Unpack the two sources: tar -xvzf gcc-2.95.2.tar.gz tar -xvzf gpc-19991030.tar.gz

2. Since GCC recommends building gcc in a separate directory, lets make one: we'll call it gcc-build. mkdir gcc-build

3. Now we need to move GPC into GCC: mv gpc/p gcc-2.95.2/gcc

4. Next is a patch to gcc: cd gcc-2.95.2/gcc patch -s -p1 < p/diffs/gcc-2.95.2.diff

5. Now GCC is ready to build several languages, including pascal. If you want to know what languages, grep language= */config-lang.in will give you a list.

6. So let's go do it: cd ../../gcc-build ../gcc-2.95.2/configure --enable-languages=pascal make bootstrap-lean

That "make bootstrap-lean" will take some time. If you want to know how much, you could date > /time1 ; make bootstrap-lean ; date > /time2

On my 400mhz i586 with 128m ram, no swap, it took 24 min 34 sec.

7. If all went well you can now install it: make install

That's it. You can find some interesting demos in /usr/local/doc/gpc/demos and you can find the units directory with find /usr/local/lib -name units

note: the following six items are untouched from the original FAQ Help! linking `gpc1' fails: `_emit_string_move' undefined (and more) ====================================================================

If linking `gpc1' bombs out with an error message that looks like this:

ld: Undefined symbol _emit_string_move _emit_string_pad _maybe_find_function_data _dbxout_set_type_status _version_flag *** Error code 1 make: Fatal error: Command failed for target `gpc1'

you probably suffer from a VPATH make problem. A few GPC source files have counterparts with identical name in the GCC source directory. When you have built GCC in the GCC source directory and you are not using a recent version of GNU make this problem may occur. There are three solutions:

1. Get a recent version of GNU make. Version 3.74 or better is known to work.

2. Build GCC in a seperate directory instead of using the GCC source directory.

3. Manually delete these files from the GCC object directory:

`stor-layout.o' `dbxout.o' `expr.o' `fold-const.o' `optabs.o' `convert.o' `function.o' `setop.o' `toplev.o'

then resume `make'.

When I build `libgpc.a', `rt0.c' says: SIGXCPU undefined (and more) =======================================================================

Compilation of the runtime system may fail in `rt0.c' with a message simular to this:

rt0.c: `SIGXCPU' undeclared (first use this function) or: rt0.c: storage size of `sv' isn't known rt0.c: storage size of `osv' isn't known

If this happens to you, you probably have run the `configure' script with the `--with-bsdrts' option while your Unix is not fully BSD compliant. The solution is to rerun `configure' without the `--with-bsdrts' switch.

I'm using Unix, and all my Pascal programs have linking problems. =================================================================

A number of Unix configurations use their system's linker instead of GNU `ld'. Usually, GPC and GCC need a program called `collect2' before calling the system's `ld'. `collect2' is installed by GCC, and if you only install GPC, it will not find `collect2', and use the system linker directly, which will result in various linker errors. The solution is to copy `collect2' by hand from the GCC directory to the location where `gpc1' lives.

How do I debug my Pascal programs? ==================================

To debug your programs, (a) GNU Pascal must be able to generate executables with debug info for your platform, and (b) you must have a debugger which understands this.

* If `gpc -g -o hello hello.p' says: `gpc: -g not supported for this platform', then GPC is unable to generate debug info. Usually, installing GAS instead of your system's assembler can overcome this. When you configure the GCC used for GPC, specify `-with-gnu-as', and possibly `-with-gnu-ld' and/or `-with-stabs'. More information can be found in `INSTALL' file in the GNU CC source directory.

* Your system's debugger may not understand the debug info generated by GNU tools. In this case, installing GDB may help.

The bottom line: if you can debug GCC compiled programs, you should be able to do this with GPC too.

The GNU debugger (GDB) currently does not have a "Pascal" mode, so it is unable to display certain Pascal structures etc. When debugging, please note that the Initial Letter In Each Identifier Is In Upper Case And The Rest Are In Lower Case. If you want to display variable `foo' in the debugger, type `show Foo' or `display Foo' instead.

Can you recommend an IDE? =========================

Users of Borland Pascal may wonder if there's a replacement for the IDE (Integrated Development Environment). Here's a few suggestions:

* (X)Emacs. Some people think it's the answer to the question of Life, the Universe and Everything, others decide it's uGNUsable. Available from your friendly GNU mirror.

* XWPE is an imitation of the Borland IDE, so users of Borland Pascal may find it a good alternative.

* RHIDE. djgpp users should definately try RHIDE. The latest (beta) release is compatible with GNU Pascal and allows stepping, tracing and watching like Borland's IDE. RHIDE v0.6 beta can be downloaded from: http://www.tu-chemnitz.de/~rho/rhidetest.html

Although GDB is an excellent debugger, it's user interface is not very attractive. Refer to the comp.windows.x FAQ: "Where can I get an X-based debugger?" at:

http://www.cis.ohio-state.edu/hypertext/faq/usenet/x-faq/part6/faq-doc-2.htm l

Some useful frontends include: XXGDB, tGDB and XWPE. see:

http://www.ee.ryerson.ca:8080/~elf/xapps/Q-IV.html

Very nice, but resource consuming is the Motif based DDD:

http://sol.ibr.cs.tu-bs.de/softech/ddd/

Do you have a binary for me? ============================

Currently, we have binaries for these platforms:

i486-linux (ELF) i486-linuxaout i486-linuxoldld i386-freebsd1.2.0 djgpp V2 (msdos) emx 0.9B (OS/2, msdos) cygwin32 beta16 (Windows95, Windows NT) mips-sgi-irix5.3 sun-sparc-sunos4.1.4

New binaries may have been added after the release of this FAQ.

3.0 GNU Pascal and your system libraries ****************************************

This section discusses common problems people have when they try to access their system's libraries.

How do I use <insert_your_function_here> from the C library? ============================================================

GNU Pascal can use every function of your C library, but it may be up to you to write declaration of an external function, before you can use it. Consider the function `sleep'. `man(3) sleep' reveals:

--------------------------------------------------------- NAME sleep - Sleep for the specified number of seconds

SYNOPSIS #include <unistd.h>

unsigned int sleep(unsigned int seconds); ---------------------------------------------------------

This small demo program shows how to use `sleep' in a Pascal program:

--------------------------------------------------------- program SleepDemo;

type word = __unsigned__ integer;

function sleep(seconds: word): word; C;

var result : word;

begin result := sleep(10); end. ----------------------------------------------------------

Are GNU Pascal objects compatible with GNU C++ classes ? ========================================================

No. (This may change in a future version)

How do I build/use a shared library? ====================================

(topic under construction)

4.0 STRINGS ***********

What's this confusion about strings? ====================================

Turbo Pascal strings have a length byte in front. Since a byte has the range 0 - 255, this limits a string to 255 characters. However, the Pascal string schema, as defined in section 6.4.3.3.3 of the ISO-10206: 1990 Extended Pascal standard, is a record:

type string = record Capacity : integer; length : integer; string : packed array [ 1..Capacity ] of char; end;

Thus at the expense of a little added complexity ( must declare capacity, don't use GetMem, and the additional space requiremnent ) you can now have very long strings.

The following Q&A is also about strings: ========================================

Q: Should the different variants in a variant record overlay in the same memory? Previous Pascals I have used have guaranteed this, and I've got low-level code that relies on this. The variants are not the same length, and they are intended not to be.

A: No, this is intentional so that the discriminants are not overwritten, and they can be properly initialized in the first place. Consider:

record case Boolean of False: (s1 : String (42)); True: (s2 : String (99)); end;

If the strings would overlay, in particular their disriminants would occupy the same place in memory. How should it be initialized? Either way, it would be wrong for at least one of the variants...

So, after a discussion in comp.lang.pascal.ansi-iso where this topic came up concerning file variables (which also require some automatic initialization and finalization), we decided to do this in GPC for all types with automatic initialization and finalization (currently files and schemata, in the future this might also be Delphi compatible classes and user-defined initialized and finalized types), since the standard does not guarantee variants to overlay, anyway...

There are two ways in GPC to get guaranteed overlaying (both non-standard, of course, since the standard does not assume anything about internal representations; both BP compatible), `absolute' declarations and variable type casts. E.g., in order to overlay a byte array to a variable v:

var b: array [1 .. SizeOf (v)] of Byte absolute v;

or

type t = array [1 .. SizeOf (v)] of Byte;

then `t (v)' can be used as a byte array overlayed to v.

In standard pascal you expect ic[1] to align with the first character position of s and thus one character to the left is the length of s. Thus ic[0] is the length of s. True?

This holds for UCSD/BP strings (which GPC does not yet implement, but that's planned). The only strings Standard Pascal knows are arrays of char without any length value.

Q: Two different kinds of strings with the same name - string - does make a bit of confusion. Perhaps the oldstyle strings could be renamed "short string" ?

A: When we implement the short strings, we'll have to do such a distinction. Our current planning goes like this:

string (n): string schema (EP compatible)

string [n]: short string (UCSD/BP compatible, where n must be <= 255)

string: dependent on flags, by default undiscriminated schema, but in BP mode (or with a special switch) short string of capacity 255 (UCSD/BP compatible). ---- Frank

Q: So when will these short strings be available?

A: It's been planned for over a year. The delay has been caused by more pressing problems.

What about C strings? ===================== A C string (`char *') is an array of char, terminated with a `NULL' char.

C library functions require C, not Pascal style string arguments. However, Pascal style strings are automatically converted to C style strings when passed to a routine that expects C style strings. This works only if the routine reads from the string, not if it modifies it.

E.g., this is how you access the `system()' call in your C library (which is not necessary any more, since `Execute' is already built-in):

--------------------------------------------------------- program SysCall;

function system(name : CString): integer; C;

var result : integer;

begin result := system ('ls -l'); writeln('system() call returned : ', result); end. ---------------------------------------------------------

There may be other ways to do the same thing; you could declare a type `PChar' instead of `CString':

type PChar = ^char;

and replace all references to `CString' with `PChar'. Do *NOT* pass a "C" style string as a var-argument if the C prototype says `const char *' or you will get a coredump.

You are right if you think this stuff belongs in a library, to be distributed with GPC. Have patience, or start coding!

5.0 GNU Pascal on the djgpp (MS-DOS) platform *********************************************

This chapter discusses some potential problems with GNU Pascal on MS-DOS, using djgpp.

If you need more information ============================

GPC/djgpp is a djgpp V2 application, and most of the djgpp documentation applies for GPC too. A great source of information is the djgpp FAQ:

http://www.delorie.com/djgpp/v2faq/faq202b.zip

Another place to look for DJGPP documentation is the DJGPP Knowledge Base, at this URL:

http://www.delorie.com/djgpp/doc/kb/

What do I download? ===================

As discussed in section 2.2, other than GPC itself, you need an assembler, linker and friends, a C library and possibly a debugger.

From your local djgpp mirror, you can get these as:

v2/djdev201.zip (C library) v2gnu/bnu270b.zip (assembler, ....) v2gnu/gdb416b.zip (debugger)

The rest is up to you; `make' (v2gnu/mak375b.zip) can be useful, The latest RHIDE test release (an IDE with Borland-look) has support for GNU Pascal, and can be downloaded from: http://www.tu-chemnitz.de/~rho/rhidetest.html

How do I install the compiler? ==============================

If you don't have djgpp installed on your harddisk, create a directory for GNU pascal (`c:\gpc'), and unzip the archives. Make sure you preserve the directory structure (use `pkunzip -d'). Now, add the directory where `gpc.exe' lives (`c:\gpc\bin') to your path and set the DJGPP environment variable to point to your `djgpp.env' file:

set DJGPP=c:\gpc\djgpp.env

Then, add this to your `djgpp.env' file:

--------------------------------------------------------- [gpc-cpp]

C_INCLUDE_PATH=%/>;C_INCLUDE_PATH%%DJDIR%/lang/pascal;%DJDIR%/include;%DJDIR %/contrib/grx20/include

[gpc] COMPILER_PATH=%/>;COMPILER_PATH%%DJDIR%/bin LIBRARY_PATH=%/>;LIBRARY_PATH%%DJDIR%/lib;%DJDIR%/contrib/grx20/lib ---------------------------------------------------------

The binary distribution should come with a `djgpp.env' which is already modified, so you may not have to do this.

The GPC online documentation is in GNU info format; you need the info reader (`txi390b.zip') to read it. To add the GPC documentation to the info directory file, edit the `c:\gpc\info\dir' file, and locate this section:

--------------------------------------------------------- * GCC: (gcc.inf). The GNU C, C++, and Objective-C Compiler

* GDB: (gdb.inf). The GNU Debugger (gdb and gdb-dpmi).

---------------------------------------------------------

To add GPC, change it to look like this:

--------------------------------------------------------- * GCC: (gcc.inf). The GNU C, C++, and Objective-C Compiler

* GPC: (gpc.inf). The GNU Pascal Compiler

* GDB: (gdb.inf). The GNU Debugger (gdb and gdb-dpmi).

---------------------------------------------------------

Specific information for low-memory conditions and more can be found in the djgpp FAQ and documentation.

I cannot read the info pages! =============================

To read the info pages, you need the `info' program from `txi390b.zip'. At least for some of the pre-releases of `gpc-1.2', the `gpc.info' file is invalid: it refers to the `gpc.i*' sections as `gpc.info-*'. This can be fixed by loading `gpc.inf' in an editor and replacing `gpc.info-*' with `gpc.i*'

GPC says: no DPMI =================

You don't have a DPMI server installed, and DJGPP v2 requires it to run. You can either use one of the commercial DPMI servers (e.g., run `gpc' in a DOS box under Windows) or download and install CWSDPMI (`csdpmi3b.zip') which is a free DPMI server written for DJGPP.

I have troubles with assembly code ==================================

The GNU Assembler (`as.exe'), or `gas', called by GCC accepts "AT&T" syntax which is different from "Intel" syntax. Differences are discussed in section 17.1 of the djgpp FAQ.

A guide is available which was written by Brennan Mr. Wacko Underwood brennan@mack.rt66.com and describes how to use inline assembly programming with DJGPP, at this URL:

http://www.rt66.com/~brennan/djgpp/djgpp_asm.html

Section 17.3 of the djgpp FAQ discusses some methods to convert "Intel" syntax to "AT&T".

Tell me how to do DPMI, BIOS and other DOS related things. ==========================================================

DPMI, BIOS and other functions are no different than other system functions. Refer to section 3.1 how to access your system's C-library. This small example shows how to use DPMI, copying some structures and function prototypes of `<dpmi.h>':

--------------------------------------------------------- program dpmitest;

{$X+}

type word = __unsigned__ integer; short = __short__ integer; byte = __byte__ integer;

type PDpmiVersionRet = ^TDpmiVersionRet; TDpmiVersionRet = record major : byte; minor : byte; flags : short; cpu : byte; master_pic : byte; slave_pic : byte; end;

type PDpmiFreeMemInfo = ^TDpmiFreeMemInfo; TDpmiFreeMemInfo = record largest_available_free_block_in_bytes : word; maximum_unlocked_page_allocation_in_pages : word; maximum_locked_page_allocation_in_pages : word; linear_address_space_size_in_pages : word; total_number_of_unlocked_pages : word; total_number_of_free_pages : word; total_number_of_physical_pages : word; free_linear_address_space_in_pages : word; size_of_paging_file_partition_in_pages : word; reserved1 : byte; reserved2 : byte; reserved3 : byte; end;

function DpmiGetVersion(ret: PDpmiVersionRet): integer; asmname '__dpmi_get_version'; function DpmiGetFreeMemoryInformation(info: PDpmiFreeMemInfo): integer; asmname '__dpmi_get_free_memory_information';

var version: TDpmiVersionRet; meminfo: TDpmiFreeMemInfo;

begin DpmiGetVersion(@version); writeln('CPU type : ', version.cpu, '86'); writeln('DPMI major : ', version.major); writeln('DPMI minor : ', version.minor);

DpmiGetFreeMemoryInformation(@meminfo); writeln('Free DPMI memory : ', meminfo.total_number_of_free_pages, ' pages.'); end. ---------------------------------------------------------

I'm accessing an `array[1..4000000] of byte' and I got an exception. ====================================================================

Per default, the maximum stack size of a djgpp application is 256K. If you need more, you have to adjust it with the stubedit program, i.e.:

stubedit your_app.exe minstack=5000K

Still, it might be a good idea to use pointers for this kind of structures, and allocate the memory at runtime.

6.0 Getting Help ****************

This section discusses ways to get help with GNU Pascal. Please read the documentation (info files, readme's) that come with GPC, plus other docs that might help (the djgpp FAQ if you use djgpp etc.) before you send email to the maintainers or mailing list.

Help! The compiler crashed! ===========================

If the compiler crashes, you have discovered a bug. A reliable compiler never crashes. To help the maintainers fix this bug, it is important that you send us a problem report.

I think I found a bug - now what? =================================

Bugs are best reported to the GPC mailinglist gpc@hut.fi. That way, they always reach the maintainers. Try to give as much information as possible, plus a short code snippet that triggers the compiler bug. If you're on Unix, you can find out where the compiler crashed if you enable coredumps, then load the compiler (`gpc1') plus the core file in the debugger (`gdb /your_path_here/gpc1 core'), then type `backtrace' to get a stacktrace. Include this stacktrace in your bug report.

Which newsgroup(s) are suited for GPC related problems? =======================================================

There are several Pascal related newsgroups, but none is dedicated just to GNU Pascal. This one may be useful:

comp.lang.pascal.misc Pascal in general and ungrouped Pascals.

Pascal syntax related questions may be appropriate in:

comp.lang.pascal.ansi-iso Pascal according to ANSI and ISO standards. comp.lang.pascal.borland Borland Pascal questions.

How to post to the mailing list ===============================

You can send a message to the GPC mailing list by sending email to the list address gpc@hut.fi as if it were a person.

How to become a subscriber to the mailing list ==============================================

You can join the mailing list by sending a message to gpc-request@hut.fi (NOT gpc@hut.fi !) with your request to be added to the list. Maintenance is done by hand, so some delay is possible.

How to unsubscribe from the mailing list ========================================

To leave the mailing list, send a message to gpc-request@hut.fi.

7.0 Miscellaneous *****************

I want to contribute; where do I start? =======================================

A list of jobs which should be done for GNU-Pascal can be found in the section "How to contribute" of the Texinfo deocumentation. In cases where somebody is already working on a topic, the name of that person is written behind the job's description.

This does not mean that you shouldn't do that but just that you should get in contact with that person if you would like to contribute to that field.

Where is the GNU Pascal FTP site? WWW? ======================================

The master FTP site for GNU Pascal is `kampi.hut.fi'. GNU Pascal related files can be found in:

ftp://ftp.kampi.hut.fi/jtv/gnu-pascal/

This site is mirrored on:

ftp://sunsite.doc.ic.ac.uk/gnu/pascal/

The latest developer releases can be downloaded from:

ftp://agnes.dida.physik.uni-essen.de/gnu-pascal/

Also, we have a homepage on the web:

http://agnes.dida.physik.uni-essen.de/~gnu-pascal/

About this FAQ. ===============

Original Maintainer: J.J. van der Heijden j.j.vanderheijden@student.utwente.nl

Current Maintainer: Russ Whitaker russwhit@mind.net

This is the second incarnation of the GNU Pascal FAQ list. Comments about, suggestions for, or corrections to this FAQ list are welcome.

Please make sure to include in your mail the version number of the document to which your comments apply (you can find the version at the beginning of this FAQ list).

Much of the info in, and inspiration for this FAQ list was taken from the gpc mailing list traffic, so you may have (unbeknownst to you) contributed to this list.