* new files

install/doc/Makefile

@@ -0,0 +1,17 @@
+##################################
+# Man page installation for linux
+#
+
+ifndef PREFIXINSTALLDIR
+PREFIXINSTALLDIR=/usr
+endif
+
+ifndef DOCINSTALLDIR
+DOCINSTALLDIR:=$(PREFIXINSTALLDIR)/doc/fpc-$(shell ppc386 -iV)
+endif 
+
+installdoc:
+	install -d -m 755 $(DOCINSTALLDIR)
+	cp readme.txt $(DOCINSTALLDIR)/README
+	cp whatsnew.txt $(DOCINSTALLDIR)/NEWS
+	cp faq.txt faq.html $(DOCINSTALLDIR)

install/doc/faq.txt

@@ -0,0 +1,470 @@
+
+                               FreePascal FAQ
+                                      
+                      As distributed with FPC 0.99.14
+                                      
+   This FAQ might not be up to date. See [1]the FPC FAQ on internet for
+   updates.
+   
+   This FAQ is in no way a substitute for the extensive documentation
+   that accompanies FPC.
+   
+    1. [2]What is Free Pascal(FPC) ?
+    2. [3]Which versions exist, and which one should I use?
+    3. [4]Known bugs
+    4. [5]Free Pascal and GNU Pascal - a comparison
+    5. [6]Where can I get the compiler ?
+    6. [7]What are the considerations in porting
+    7. [8]I tried to compile my Delphi code with the Free Pascal
+       Compiler,
+    8. [9]I have to write a program for homework. Can you help?
+    9. [10]How can I build a unit?
+   10. [11]Will Free Pascal support TV (Turbo Vision) in the future?
+   11. [12]How can I compile the system unit ?
+   12. [13]I get an internal error 9999
+   13. [14]How does function overloading work?
+   14. [15]How can I call C functions ?
+   15. [16]When will Free Pascal use DJGPP 2.0 under DOS/Windows ?
+   16. [17]How can I use the graph unit with Free Pascal ?
+   17. [18]Integrated Assembler syntax
+   18. [19]How to access DOS memory / How to do graphics ?
+   19. [20]Free Pascal without a math coprocessor
+   20. [21]Accessing more than 4 megabytes
+   21. [22]Access I/O ports
+   22. [23]I'm using the Dos compiler under Windows 95
+   23. [24]I'm using OS/2
+   24. [25]INSTALL.EXE of Dos version 0.99.10 reports "Load error: no
+       DPMI"
+   25. [26]INSTALL.EXE of Dos version 0.99.10 does not run in Windows NT
+   26. [27]I want a new version NOW
+   27. [28]Where can I find a text mode IDE for Dos
+   28. [29]How do I configure the Dos IDE
+   29. [30]Why are the generated binaries so big?
+   30. [31]Unit system, syslinux or syswin32 not found errors
+       
+   
+    1. What is Free Pascal(FPC) ?
+       Originally named FPK-Pascal, the Free Pascal compiler is a 32 bit
+       Turbo Pascal compatible Pascal compiler for DOS, Linux, Win32,
+       OS/2 and (based on an older version) the AmigaOS. More Operating
+       systems are in the works.
+       The compiler is written in Pascal and is able to compile its own
+       sources. The source files are included.
+       Free Pascal requires a fast computer to run efficiently (386-25
+       Mhz for the Intel version and ideally a 68020 processor for the
+       Motorola version). At least 2 megabytes of RAM is required. To
+       remake the compiler more than 16 is recommended.
+       Short history:
+        6/1993 project start
+       10/1993 first little programs work
+        3/1995 the compiler compiles the own sources
+        3/1996 released to the internet
+        probably 2000 1.0 version
+    2. Which versions exist, and which one should I use?
+       Compilers with an even last number are release versions(e.g.
+       0.99.8, 0.99.10, 0.99.12 and 0.99.14)
+       Compilers and packages with an odd last number are development
+       versions (e.g. 0.99.9, 0.99.11, 0.99.13 and 0.99.15).
+       0.99.5 is an exception to this rule, since 0.99.5 IS a release (a
+       release prior to the introduction of this odd/even system)
+       Letters behind the version number (0.99.12b, 0.99.5d) indicate
+       release versions with some bugs and problems in the original
+       release (respectively 0.99.12 and 0.99.5) fixed.
+       Normally you would want to use a release. Releases are considered
+       stable, and easier to support. (the bugs, quirks and unintended
+       "features" are wellknown after a period of time, and workarounds
+       exist).
+       Development snapshots which are generated daily reflect the
+       current status of the compiler. Development versions probably have
+       new features and larger bugs fixed since the last release, but
+       might have some temporary stability drawbacks, (btw which are
+       usually fixed quite soon)
+       Most support for development snapshots are basically the advise to
+       upgrading to newer snapshot in which the bugs are hopefully fixed.
+       Since version 0.99.8 the stability of the compiler steadily
+       increased, and development snapshots are often quite useful for
+       certain categories of users. Ask in the maillists if it is worth
+       the effort in your case.
+       The current release version is 0.99.14 for the OS/2,Linux,Windows
+       and Dos (Go32V2) targets,
+       and 0.99.5d for the 680x0 based systems (mainly Amiga and Mac)
+       The current development snapshot version is 0.99.13 or 0.99.15.
+    3. Known bugs
+       Go to the [32]bugs page
+    4. Free Pascal and GNU Pascal - a comparison
+       
+        aim:
+                Free Pascal tries to implement a Borland compatible
+                pascal compiler on as many platforms as possible. GNU
+                Pascal tries to implement a portable pascal compiler
+                based on POSIX.
+                
+        Version:
+                Currently, Free Pascal is at version 0.99.12 for the
+                Intel version, and version 1.0 will be out soon, and
+                version 0.99.5d for the Motorola/Intel version. Version
+                0.99.5d differs from version 0.99.5 in that all run time
+                library fixes have been applied, as well as all known
+                code generation bugs. Version 0.99.12 differs from
+                version 0.99.5c in that all parser bugfixes have also
+                been applied and also a lot of Delphi 2 and Delphi 3
+                extensions have been implemented. GNU Pascal is at
+                version 2.7.2 (but this numbering is not really an
+                indication, it follows the GNU C numbering, since it is a
+                derivation of it)
+                
+        Operating systems:
+                Free pascal runs on a limited number of systems : DOS,
+                Win32, Linux, OS/2 and AmigaOS and is for the moment
+                limited to the Intel and Motorola architectures. GNU
+                Pascal runs basically on any system that can run GNU C.
+                
+        Sources:
+                Free Pascal is entirely written in Pascal (about 4 Mb of
+                source code), while GNU Pascal is written in C (it's an
+                adaptation of the GNU C compiler : 2.8 Mb code + 8 MB of
+                GNU C code)
+                
+        Language:
+                Free Pascal supports the Borland Pascal dialect Borland,
+                and implements the Delphi Object PAscal language. GNU
+                Pascal supports ISO 7185, ISO 10206, (most of) Borland
+                Pascal 7.0
+                
+        Extensions:
+                Free Pascal implements function overloading, and operator
+                overloading). GNU Pascal implements operator overloading.
+                
+        License:
+                Both compilers come under the GNU GPL.
+                
+        Author:
+                Free Pascal was started by Florian Klaempfl, Germany
+                ([email protected]), GNU Pascal was
+                started by Jukka Virtanen, Finland, ([email protected]).
+                
+   
+    5. Where can I get the compiler ?
+       Free Pascal is available for download from all [33]official
+       mirrors
+    6. What are the considerations in porting code to other processors?
+       Because the compiler now supports processors other than the Intel,
+       it is important to take a few precautions so that your code will
+       execute correctly on all processors.
+          + Limit your use of asm statements unless it is time critical
+            code
+          + Don't use the packed directive unless you know exactly what
+            you are doing. Most processors require alignment of data, and
+            using packed on objects,classes and records may break this
+            requirement. If this is the case your code will simply crash
+            on the target processors.
+          + Clean up at the end of your program, i.e close all files on
+            exit, as some operating systems don't like it when some files
+            are left opened.
+          + Try not to rely on the endian of the specific machines when
+            doing arithmetic operations. Furthermore, reading and writing
+            of binary data to/from files will probably require byte swaps
+            across different endian machines (swap is your friend in this
+            case)
+          + Try limiting your local variables in subroutines to 32K, as
+            this is the limit of some processors, use dynamic allocation
+            instead.
+          + Try limiting the size of parameters passed to subroutines to
+            32K, as this is the limit of some processors, use const or
+            var parameters instead.
+   
+    7. I tried to compile my Delphi code with the Free Pascal Compiler,
+       it seems that it doesn't recognize the OOP.
+       The compiler supports the Delphi OOP. There may be some bugs, of
+       course, You should try the -S2, -Sd or -So switches (see the
+       manuals for the meaning of these switches)
+    8. I have to write a program for homework. Can you help?
+       No. Please, don't send us mail about homework, we are no teachers.
+       The Free Pascal development team tries to give good support for
+       the Free Pascal compiler and are trying to always reply to emails.
+       If we get emails like this, this becomes harder and harder.
+    9. How can I build a unit?
+       It works like in Turbo Pascal. The first keyword in the file must
+       be UNIT (not case sensitive). The compiler will generate two
+       files: XXX.PPU and XXX.O. The PPU file contains the interface
+       information for the compiler and the O-file the machine code (an
+       object file, whose precise structure depends on the assembler you
+       used). To use this unit in another unit or program, you must
+       include its name in the USES clause of your program.
+   10. Will Free Pascal support TV (Turbo Vision) in the future?
+       A Turbo Vision port, called Free Vision, has progressed nicely
+       lately. It's already very usable, we are even writing an IDE in
+       it. Due to copyrights problem the FreeVision source code is not
+       available at the moment. You can download the IDE from the
+       [34]development page. and get an idea of the look and feel though.
+   11. How can I compile the system unit ?
+       To recompile the system unit, it is recommended to have GNU make
+       installed. typing 'make' in the rtl source directory will then
+       recompile all RTL units including the system unit. You may choose
+       to descend into the directory of your OS (e.g. rtl/go32v2) and do
+       a 'make' there.
+       It is possible to do all this manually, but you need more detailed
+       knowledge of the RTL tree structure for that.
+   12. I get an internal error 9999
+       The latest versions of the Free Pascal Compiler come with a Error
+       Handling routine which catches the segmentation fault, and lets
+       the compiler exit gracefully. This is reported as an internal
+       error 9999.
+       Please try to reproduce the error and send [35]us a bug report.
+       (For the curious, IE 9999 is not a specific bug. It is a safety
+       measure which terminates if during compiling a certain condition
+       is not met, which can be caused by several bugs. So if you report
+       the bug, and get IE 9999 later in a different piece or part of
+       sourcecode, it could be a completely different bug)
+   13. How does function overloading work?
+       function overloading is implemented, like in C++:
+  procedure a(i : integer);
+
+   begin
+   end;
+
+  procedure a(s : string);
+
+   begin
+   end;
+
+  begin
+
+   a('asdfdasf");
+   a(1234);
+  end.
+       You must be careful. If one of your overloaded functions is in the
+       interface part of your unit, then all overloaded functions must be
+       in the interface part. If you leave one out, the compiler will
+       complain with a 'This overloaded function can't be local' message.
+       Overloaded functions must differ in their parameters, it's not
+       enough if their return types are different.
+   14. How can I call C functions ?
+       C calling convention is implemented as follows: The compiler
+       pushes the parameters from right to left, but the procedure has to
+       clear the stack. For calling the C function strcmp declare the
+       following:
+  function strcmp(s1 : pchar;s2 : pchar) : integer;cdecl;external;
+  Since 0.99.5, the older [C]; won't work!
+   
+   15. When will Free Pascal use DJGPP 2.0 under DOS/Windows ?
+       As of version 0.99.0 Free Pascal uses DJGPP 2.0. DJGPP v1.2
+       support has been removed since version FPC 0.99.8.
+   16. How can I use the graph unit with Free Pascal ?
+       Look at InitGraph.
+   17. Integrated Assembler syntax
+       The default assembler syntax (AT&T style) is different from the
+       one in Borland Pascal (Intel style).
+       However, as of version 0.99.0, the compiler supports Intel style
+       assembly syntax. See the documentation for more info on how to use
+       different assembler styles.
+       A description of the AT&T syntax can be found in the DJGPP FAQ
+       [36]http://www.delorie.com/djgpp/v2faq/faq102.html#Syntax or in
+       Brennan's Guide to Inline Assembly
+       [37]http://www.rt66.com/~brennan/djgpp/djgpp_asm.html. The
+       documentation also contains a chapter where the difference between
+       the Intel and AT&T style assembly is explained.
+       Or you can use the convertor program at
+       http://rcs.urz.tu-dresden.de/ schoenfu/zip/asmtrans.zip.
+   18. How to access DOS memory / How to do graphics ?
+       You can do like in TP, via absolute or mem, for larger blocks use
+       the dosmemput/dosmemget routines in unit Go32
+   19. Free Pascal without a math coprocessor
+       On the Intel version the emulator is automatically loaded by the
+       compiler, the file is bin\emu387.
+  SET GO32=EMU C:\PP\BIN\EMU387
+   
+   20. Accessing more than 4 megabytes
+       By default Free Pascal allocates only 4 meg. If it just allocated
+       all it could get, people running windows would have problems as
+       Windows would increase the swap file size to give the program more
+       memory on and on, until the swap file drive would be full.
+       You can specify the size of the heap with -Chxxxx. The default
+       value is -Ch4000000. Try -Ch10000000, provided you got enough swap
+       space.
+       However, the heap size doesn't really matter anymore, since the
+       Heap is able to grow. That is, if you've used all available heap
+       space, the program will try to get more memory from the OS, thus
+       the heap is limited to the maximum amount of free memory provided
+       by the OS.
+   21. Access I/O ports
+       If you're under DOS, you should use the outport* and inport*
+       procedures of the go32 unit.
+       Since version 0.99.8, the Port array is supported like in TP, as
+       long as you use the ports unit in your program.
+   22. I'm using the Dos compiler under Windows 95
+       There is a problem with the Dos compiler and Win 95 on computers
+       with less than 16 MB. First set in the properties of the DOS box
+       the DPMI memory size to max value. Now try to start a demo program
+       in the DOS box, e.g. HELLO (starting takes some time). If this
+       works you will be able to get the compiler to work by recompiling
+       it with a smaller heap size, perhaps 2 or 4 MB (option -Chxxxx).
+   23. I'm using OS/2
+       Problems have been reported that the Go32v2 compiler does not run
+       on some OS/2 installations. You can use the native OS/2 compiler,
+       or compile a GO32V1 compiler yourself.
+   24. INSTALL.EXE of Dos version 0.99.10 reports "Load error: no DPMI"
+       The file cwsdpmi.exe is missing in the main directory of the zip
+       archive. The above message pops up of no other DPMI services are
+       available. Such services are for example available in a Dos window
+       of Windows. You can either extract that file from basego32.zip or
+       download it from
+       [38]http://www.brain.uni-freiburg.de/~klaus/cwsdpmi.exe. Put it
+       into the same directory as install.exe and run install again.
+   25. INSTALL.EXE of Dos version 0.99.10 does not run in Windows NT
+       This is an incompatibility of the mouse driver. Use this new
+       version of install.exe instead:
+       [39]ftp://ftp.freepascal.org/pub/fpc/snapshot/install.exe
+   26. I want a new version NOW
+       In the time between the release of new official versions, you can
+       have a look at and test developer versions. Be warned though: this
+       is work under progress, so in addition to old bugs fixed and new
+       features added, this may also contain new bugs. The snapshot is
+       generated automatically each night from the current source at that
+       moment. Somethimes this may fail due to bigger changes not yet
+       fully implemented. If your version doesn't work, try again one or
+       two days later. Don't download the Go32V1 version for Dos, it's
+       not supported any more.
+       The latest snapshot can be downloaded from the [40]development web
+       page.
+       To install a snapshot, extract the zip archive into the existing
+       program directory of the last official version of fee pascal
+       (after making a backup of the original of course). Or extract it
+       into an empty directory, then move the files to the program
+       directory, overwriting existing files. Make sure that you extract
+       the ZIP archiv such that the included directory structure remains
+       intact, for example if you use PKUNZIP, use "pkuzip -d" instead of
+       just "pkunzip".
+   27. Where can I find a text mode IDE for Dos
+       The development of the IDE (integrated development environment) is
+       not yet finished. However a working test version of the IDE is
+       available as snapshot. It requires the latest compiler snapshot be
+       installed on top of the last official Dos version 0.99.12 for
+       Go32V2. So if you have not already done it, first install the last
+       official version (file dos09912.zip or dos09912full.zip, you find
+       these in the [41]download section). Then get and extract the
+       latest Dos snapshot for DOS-GO32V2 (snapshot.zip) into the
+       directory containing the last official version. Then do the same
+       with one of the IDE snapshots (the debugger does not work very
+       well yet, so start with the version "IDE with compiler"). For more
+       details on where to find and how to install a snapshot, please see
+       the previous FAQ item. For additional instructions for required
+       IDE configuration please also read the next FAQ item.
+   28. How do I configure the Dos IDE
+       Once you have installed the IDE (see the previous FAQ item), it
+       requires two configuration changes before it can compile. This is
+       due to the fact that the IDE includes its own compiler, it does
+       not use ppc386.exe and thus it also does not use the configuration
+       in the file ppc386.cfg. Thus if you try to compile, you get an
+       error message telling that it can not compile the system unit. To
+       fix this start fp.exe, select from the menu Compile, then Target
+       then Go32V2. Next select the menu Options/Directories and in the
+       line "Unit directories" enter the path to your copy of the rtl
+       directory, usually c:\pp\units\go32v2\rtl. If you have done
+       everything correct and it still doesn't work, you may have grabbed
+       a snapshot that has a bug, in this case try again one or two days
+       later.
+   29. Why are the generated binaries so big?
+       There are several reasons and remedies for this.
+       
+    1. If you are using 0.99.12: Due to some problems with the binary
+       writer, the 0.99.12 and fixes weren't released with smartlinking
+       RTLs. Smartlinking causes only actually used procedures, functions
+       and constants to be linked in.
+       You can remedy this by using a development version and creating a
+       smartlinking RTL. See the [42]make cycle faq or use a later
+       release if available.
+    2. Generating debug code (-g options) is enabled. Use the strip
+       utility (or stripw for the windows platform) to remove the
+       debuginformation.
+       The utility is supplied with the releases, except under Linux were
+       it is part of the GNU binutils package.
+    3. Under Dos(Go32V2) and windows targets you can use UPX to pack the
+       .EXEs (just like e.g. pklite). The architecture of linux doesn't
+       allow binary packing.
+    4. Turning on optimalisations, both for supplied packages
+       (RTL,API,FV,FCL) as for your own code, will also decrease
+       code-size.
+       
+     Unit system, syslinux or syswin32 not found errors
+   
+   System (syslinux, syswin32 depending on platform) is Pascal's base
+   unit which is invisibly used in all programs. This unit defines
+   several standard procedures and structures, and must be found to be
+   able to compile any pascal program by FPC.
+   
+   The location of the system.ppu and syslinux.o files are determined by
+   the -Fu switch which can be specified commandline, but is usually in
+   the ppc386.cfg (Win32: ppc386w.cfg) configuration file.
+   If the compiler can't find this unit there are three possible causes:
+    1. The ppc386.cfg isn't in the same path as the compiler (go32v2 and
+       win32), or in /etc/ppc386.cfg or as .ppc386.cfg in your
+       homedirectory (Linux).
+    2. The ppc386.cfg doesn't contain the -Fu line, or a wrong one. See
+       the [43]make cycle faq specially the chapters about the ppc386.cfg
+       and the directory structure.
+    3. The files ARE found but the wrong version or platform. Correct
+       ppc386.cfg to point to the right versions, or reinstall the right
+       versions.
+       
+   A handy trick can be executing "ppc386 programname -vt", this shows
+   where the compiler is currently looking for the system unit's files.
+   You might want to pipe this through more(dos,windows) or less(Linux),
+   since it can generate more than one screen information:
+Dos,Windows:
+
+
+ppc386 programname -vt |more
+
+
+
+Linux:
+
+
+ppc386 programname -vt |less
+
+References
+
+   1. http://www.freepascal.org/faq.html
+   2. file://localhost/home/pfv/cvs/install/doc/faq.html#WhatIsFP
+   3. file://localhost/home/pfv/cvs/install/doc/faq.html#versions
+   4. file://localhost/home/pfv/cvs/install/doc/faq.html#KnownBugs
+   5. file://localhost/home/pfv/cvs/install/doc/faq.html#FPandGNUPascal
+   6. file://localhost/home/pfv/cvs/install/doc/faq.html#WhereToGetFP
+   7. file://localhost/home/pfv/cvs/install/doc/faq.html#PortabilityTips
+   8. file://localhost/home/pfv/cvs/install/doc/faq.html#OOP
+   9. file://localhost/home/pfv/cvs/install/doc/faq.html#HOMEWORK
+  10. file://localhost/home/pfv/cvs/install/doc/faq.html#HowcanIbuildaunit
+  11. file://localhost/home/pfv/cvs/install/doc/faq.html#TurboVision
+  12. file://localhost/home/pfv/cvs/install/doc/faq.html#CompileSystemUnit
+  13. file://localhost/home/pfv/cvs/install/doc/faq.html#Internalerror9999
+  14. file://localhost/home/pfv/cvs/install/doc/faq.html#Howdoesfunctionoverloadingwork
+  15. file://localhost/home/pfv/cvs/install/doc/faq.html#HowToCallCFuncuntions
+  16. file://localhost/home/pfv/cvs/install/doc/faq.html#DJGPP2support
+  17. file://localhost/home/pfv/cvs/install/doc/faq.html#HowToUseGraph
+  18. file://localhost/home/pfv/cvs/install/doc/faq.html#IntegratedAssemblerSyntax
+  19. file://localhost/home/pfv/cvs/install/doc/faq.html#HowToAccessDosMemory
+  20. file://localhost/home/pfv/cvs/install/doc/faq.html#FPwithoutfpu
+  21. file://localhost/home/pfv/cvs/install/doc/faq.html#AccessingMoreThan4MB
+  22. file://localhost/home/pfv/cvs/install/doc/faq.html#accessioports
+  23. file://localhost/home/pfv/cvs/install/doc/faq.html#ImusingWin95
+  24. file://localhost/home/pfv/cvs/install/doc/faq.html#ImusingOS2
+  25. file://localhost/home/pfv/cvs/install/doc/faq.html#dpmi
+  26. file://localhost/home/pfv/cvs/install/doc/faq.html#winnt
+  27. file://localhost/home/pfv/cvs/install/doc/faq.html#snapshot
+  28. file://localhost/home/pfv/cvs/install/doc/faq.html#ideinst
+  29. file://localhost/home/pfv/cvs/install/doc/faq.html#ideconfig
+  30. file://localhost/home/pfv/cvs/install/doc/faq.html#binariesbig
+  31. file://localhost/home/pfv/cvs/install/doc/faq.html#systemnotfound
+  32. http://www.freepascal.org/bugs.html
+  33. http://www.freepascal.org/download.html
+  34. http://www.freepascal.org/develop.html#snapshot
+  35. http://www.freepascal.org/moreinfo.html
+  36. http://www.delorie.com/djgpp/v2faq/faq102.html#Syntax
+  37. http://www.rt66.com/~brennan/djgpp/djgpp_asm.html
+  38. http://www.brain.uni-freiburg.de/~klaus/cwsdpmi.exe
+  39. ftp://ftp.freepascal.org/pub/fpc/snapshot/install.exe
+  40. http://www.freepascal.org/develop.html#snapshot
+  41. http://www.freepascal.org/download.html
+  42. http://www.freepascal.org/makecyc.html
+  43. http://www.freepascal.org/makecyc.html