ARM Club 3/TheARMClub_PDCD3.iso/hensa/programming/gpc_2/!gcc/docs/pascal/gpc

GNU Info File | 1996-11-11 | 339.8 KB | 8,855 lines

This is Info file ^.!gcc.docs.pascal.gpc, produced by Makeinfo-1.63
from the input file texi.gpc.

   This file documents the use of the GNU Pascal compiler.

   Copyright (C) 1988, 1996 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License," "Funding for
Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License," "Funding for Free Software," and "Protect Your Freedom--Fight
`Look And Feel'", and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.


File: ^.!gcc.docs.pascal.gpc,  Node: Top,  Next: Copying,  Up: (DIR)

GNU Pascal
**********

   This manual documents how to run and install the GNU Pascal compiler
(GPC), as well as its new features and incompatibilities, and how to
report bugs.  It corresponds to GPC version 1.2 (2.7.2).

* Menu:

* Copying::           GNU General Public License says
                      how you can copy and share GPC.
* Contributors::      People who have contributed to GPC.
* Funding::           How to help assure funding for free software.
* Look and Feel::     Protect your freedom--fight "look and feel".
* Manifesto::         What's GNU?  GNU's Not Unix!

* Purpose::           The Purpose of GNU Pascal.
* Installation::      How to configure, compile and install GNU Pascal.
* Invoking GPC::      Command options supported by `gpc'.

* Keywords::          Pascal Keywords and operators supported by GNU Pascal.
* Built-in::          Other built-in Identifiers.
* Extensions::        Extensions to Standard Pascal supported by GPC.
* Extended Pascal::   About Pascal and Extended Pascal languages.
* Borland Pascal::    A QuickStart guide from Borland Pascal to GNU Pascal.

* FPK Pascal::        A comparision between the FreeWare compilers
                      FPK Pascal and GNU Pascal.

* GPC Bugs::          Known bugs and inconveniences; how to report bugs.
* How to Contribute:: How *you* can contribute to the GNU Pascal project.

* Index::          Index of concepts and symbol names (incomplete).


File: ^.!gcc.docs.pascal.gpc,  Node: Copying,  Next: Contributors,  Prev: Top,  Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

   The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY

 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

   If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR

     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.

     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.

     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.

     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.


File: ^.!gcc.docs.pascal.gpc,  Node: Contributors,  Next: Funding,  Prev: Copying,  Up: Top

Contributors to GNU Pascal
**************************

   GNU Pascal is the work of Jukka Virtanen.  Several people have
contributed to GNU Pascal.

   * Peter Gerwinski wrote the Borland Pascal (and other) extensions to
     GPC.

   * Jan Jaap van der Heijden ported GPC to various platforms and wrote
     the auto-configuration scripts.

   GNU Pascal is based on GNU CC by Richard Stallman.  Several people
have contributed to GNU CC.

   * The idea of using RTL and some of the optimization ideas came from
     the program PO written at the University of Arizona by Jack
     Davidson and Christopher Fraser.  See "Register Allocation and
     Exhaustive Peephole Optimization", Software Practice and
     Experience 14 (9), Sept. 1984, 857-866.

   * Paul Rubin wrote most of the preprocessor.

   * Leonard Tower wrote parts of the parser, RTL generator, and RTL
     definitions, and of the Vax machine description.

   * Ted Lemon wrote parts of the RTL reader and printer.

   * Jim Wilson implemented loop strength reduction and some other loop
     optimizations.

   * Nobuyuki Hikichi of Software Research Associates, Tokyo,
     contributed the support for the Sony NEWS machine.

   * Charles LaBrec contributed the support for the Integrated Solutions
     68020 system.

   * Michael Tiemann of Cygnus Support wrote the support for inline
     functions and instruction scheduling.  Also the descriptions of the
     National Semiconductor 32000 series cpu, the SPARC cpu and part of
     the Motorola 88000 cpu.

   * Jan Stein of the Chalmers Computer Society provided support for
     Genix, as well as part of the 32000 machine description.

   * Randy Smith finished the Sun FPA support.

   * Robert Brown implemented the support for Encore 32000 systems.

   * David Kashtan of SRI adapted GNU CC to VMS.

   * Alex Crain provided changes for the 3b1.

   * Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX
     for the 9000 series 300.

   * William Schelter did most of the work on the Intel 80386 support.

   * Christopher Smith did the port for Convex machines.

   * Paul Petersen wrote the machine description for the Alliant FX/8.

   * Dario Dariol contributed the four varieties of sample programs
     that print a copy of their source.

   * Alain Lichnewsky ported GNU CC to the Mips cpu.

   * Devon Bowen, Dale Wiles and Kevin Zachmann ported GNU CC to the
     Tahoe.

   * Jonathan Stone wrote the machine description for the Pyramid
     computer.

   * Gary Miller ported GNU CC to Charles River Data Systems machines.

   * Richard Kenner of the New York University Ultracomputer Research
     Laboratory wrote the machine descriptions for the AMD 29000, the
     DEC Alpha, the IBM RT PC, and the IBM RS/6000 as well as the
     support for instruction attributes.  He also made changes to
     better support RISC processors including changes to common
     subexpression elimination, strength reduction, function calling
     sequence handling, and condition code support, in addition to
     generalizing the code for frame pointer elimination.

   * Richard Kenner and Michael Tiemann jointly developed reorg.c, the
     delay slot scheduler.

   * Mike Meissner and Tom Wood of Data General finished the port to the
     Motorola 88000.

   * Masanobu Yuhara of Fujitsu Laboratories implemented the machine
     description for the Tron architecture (specifically, the Gmicro).

   * James van Artsdalen wrote the code that makes efficient use of the
     Intel 80387 register stack.

   * Mike Meissner at the Open Software Foundation finished the port to
     the MIPS cpu, including adding ECOFF debug support, and worked on
     the Intel port for the Intel 80386 cpu.

   * Ron Guilmette implemented the `protoize' and `unprotoize' tools,
     the support for Dwarf symbolic debugging information, and much of
     the support for System V Release 4.  He has also worked heavily on
     the Intel 386 and 860 support.

   * Torbjorn Granlund implemented multiply- and divide-by-constant
     optimization, improved long long support, and improved leaf
     function register allocation.

   * Mike Stump implemented the support for Elxsi 64 bit CPU.

   * John Wehle added the machine description for the Western Electric
     32000 processor used in several 3b series machines (no relation to
     the National Semiconductor 32000 processor).


File: ^.!gcc.docs.pascal.gpc,  Node: Funding,  Next: Look and Feel,  Prev: Contributors,  Up: Top

Funding Free Software
*********************

   If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development.  The most effective approach known is to encourage
commercial redistributors to donate.

   Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers--the Free Software Foundation, and others.

   The way to convince distributors to do this is to demand it and
expect it from them.  So when you compare distributors, judge them
partly by how much they give to free software development.  Show
distributors they must compete to be the one who gives the most.

   To make this approach work, you must insist on numbers that you can
compare, such as, "We will donate ten dollars to the Frobnitz project
for each disk sold."  Don't be satisfied with a vague promise, such as
"A portion of the profits are donated," since it doesn't give a basis
for comparison.

   Even a precise fraction "of the profits from this disk" is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably less
than a dollar; it might be a few cents, or nothing at all.

   Some redistributors do development work themselves.  This is useful
too; but to keep everyone honest, you need to inquire how much they do,
and what kind.  Some kinds of development make much more long-term
difference than others.  For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much.  Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU C compiler contribute more;
major new features or packages contribute the most.

   By establishing the idea that supporting further development is "the
proper thing to do" when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.

     Copyright (C) 1994 Free Software Foundation, Inc.
     Verbatim copying and redistribution of this section is permitted
     without royalty; alteration is not permitted.


File: ^.!gcc.docs.pascal.gpc,  Node: Look and Feel,  Next: Manifesto,  Prev: Funding,  Up: Top

Protect Your Freedom--Fight "Look And Feel"
*******************************************

     This section is a political message from the League for Programming
     Freedom to the users of GNU CC.  We have included it here because
     the issue of interface copyright is important to the GNU project.

   Apple, Lotus, and now CDC have tried to create a new form of legal
monopoly: a copyright on a user interface.

   An interface is a kind of language--a set of conventions for
communication between two entities, human or machine.  Until a few years
ago, the law seemed clear: interfaces were outside the domain of
copyright, so programmers could program freely and implement whatever
interface the users demanded.  Imitating de-facto standard interfaces,
sometimes with improvements, was standard practice in the computer
field.  These improvements, if accepted by the users, caught on and
became the norm; in this way, much progress took place.

   Computer users, and most software developers, were happy with this
state of affairs.  However, large companies such as Apple and Lotus
would prefer a different system--one in which they can own interfaces
and thereby rid themselves of all serious competitors.  They hope that
interface copyright will give them, in effect, monopolies on major
classes of software.

   Other large companies such as IBM and Digital also favor interface
monopolies, for the same reason: if languages become property, they
expect to own many de-facto standard languages.  But Apple and Lotus are
the ones who have actually sued.  Apple's lawsuit was defeated, for
reasons only partly related to the general issue of interface copyright.

   Lotus won lawsuits against two small companies, which were thus put
out of business.  Then they sued Borland; they won in the trial court
(no surprise, since it was the same court that had ruled for Lotus twice
before), but the decision was reversed by the court of appeals, with
help from the League for Programming Freedom in the form of a
friend-of-the-court brief.  We are now waiting to see if the Supreme
Court will hear the case.  If it does, the League for Programming
Freedom will again submit a brief.

   The battle is not over.  Just this summer a company that produced a
simulator for a CDC computer was shut down by a copyright lawsuit by
CDC, which charged that the simulator infringed the copyright on the
manuals for the computer.

   If the monopolists get their way, they will hobble the software
field:

   * Gratuitous incompatibilities will burden users.  Imagine if each
     car manufacturer had to design a different way to start, stop, and
     steer a car.

   * Users will be "locked in" to whichever interface they learn; then
     they will be prisoners of one supplier, who will charge a
     monopolistic price.

   * Large companies have an unfair advantage wherever lawsuits become
     commonplace.  Since they can afford to sue, they can intimidate
     smaller developers with threats even when they don't really have a
     case.

   * Interface improvements will come slower, since incremental
     evolution through creative partial imitation will no longer occur.

   If interface monopolies are accepted, other large companies are
waiting to grab theirs:

   * Adobe is expected to claim a monopoly on the interfaces of various
     popular application programs, if Lotus ultimately wins the case
     against Borland.

   * Open Computing magazine reported a Microsoft vice president as
     threatening to sue people who imitate the interface of Windows.

   Users invest a great deal of time and money in learning to use
computer interfaces.  Far more, in fact, than software developers
invest in developing *and even implementing* the interfaces.  Whoever
can own an interface, has made its users into captives, and
misappropriated their investment.

   To protect our freedom from monopolies like these, a group of
programmers and users have formed a grass-roots political organization,
the League for Programming Freedom.

   The purpose of the League is to oppose monopolistic practices such as
interface copyright and software patents.  The League calls for a return
to the legal policies of the recent past, in which programmers could
program freely.  The League is not concerned with free software as an
issue, and is not affiliated with the Free Software Foundation.

   The League's activities include publicizing the issues, as is being
done here, and filing friend-of-the-court briefs on behalf of
defendants sued by monopolists.

   The League's membership rolls include Donald Knuth, the foremost
authority on algorithms, John McCarthy, inventor of Lisp, Marvin Minsky,
founder of the MIT Artificial Intelligence lab, Guy L.  Steele, Jr.,
author of well-known books on Lisp and C, as well as Richard Stallman,
the developer of GNU CC.  Please join and add your name to the list.
Membership dues in the League are $42 per year for programmers, managers
and professionals; $10.50 for students; $21 for others.

   Activist members are especially important, but members who have no
time to give are also important.  Surveys at major ACM conferences have
indicated a vast majority of attendees agree with the League on both
issues (interface copyrights and software patents).  If just ten percent
of the programmers who agree with the League join the League, we will
probably triumph.

   To join, or for more information, phone [phone] or write to:

     League for Programming Freedom
     1 Kendall Square #143
     P.O. Box 9171
     Cambridge, MA 02139

   You can also send electronic mail to `[e-mail]'.

   In addition to joining the League, here are some suggestions from the
League for other things you can do to protect your freedom to write
programs:

   * Tell your friends and colleagues about this issue and how it
     threatens to ruin the computer industry.

   * Mention that you are a League member in your `.signature', and
     mention the League's email address for inquiries.

   * Ask the companies you consider working for or working with to make
     statements against software monopolies, and give preference to
     those that do.

   * When employers ask you to sign contracts giving them copyright on
     your work, insist on a clause saying they will not claim the
     copyright covers imitating the interface.

   * When employers ask you to sign contracts giving them patent rights,
     insist on clauses saying they can use these rights only
     defensively.  Don't rely on "company policy," since that can
     change at any time; don't rely on an individual executive's
     private word, since that person may be replaced.  Get a commitment
     just as binding as the commitment they get from you.

   * Write to Congress to explain the importance of these issues.

          House Subcommittee on Intellectual Property
          2137 Rayburn Bldg
          Washington, DC 20515

          Senate Subcommittee on Patents, Trademarks and Copyrights
          United States Senate
          Washington, DC 20510

     (These committees have received lots of mail already; let's give
     them even more.)

   Democracy means nothing if you don't use it.  Stand up and be
counted!


File: ^.!gcc.docs.pascal.gpc,  Node: Manifesto,  Next: Purpose,  Prev: Look and Feel,  Up: Top

The GNU Manifesto
*****************

     The GNU Manifesto which appears below was written by Richard
     Stallman at the beginning of the GNU project, to ask for
     participation and support.  For the first few years, it was
     updated in minor ways to account for developments, but now it
     seems best to leave it unchanged as most people have seen it.

     Since that time, we have learned about certain common
     misunderstandings that different wording could help avoid.
     Footnotes added in 1993 help clarify these points.

     For up-to-date information about the available GNU software,
     please see the latest issue of the GNU's Bulletin.  The list is
     much too long to include here.

What's GNU?  Gnu's Not Unix!
============================

   GNU, which stands for Gnu's Not Unix, is the name for the complete
Unix-compatible software system which I am writing so that I can give it
away free to everyone who can use it.(1) Several other volunteers are
helping me.  Contributions of time, money, programs and equipment are
greatly needed.

   So far we have an Emacs text editor with Lisp for writing editor
commands, a source level debugger, a yacc-compatible parser generator,
a linker, and around 35 utilities.  A shell (command interpreter) is
nearly completed.  A new portable optimizing C compiler has compiled
itself and may be released this year.  An initial kernel exists but
many more features are needed to emulate Unix.  When the kernel and
compiler are finished, it will be possible to distribute a GNU system
suitable for program development.  We will use TeX as our text
formatter, but an nroff is being worked on.  We will use the free,
portable X window system as well.  After this we will add a portable
Common Lisp, an Empire game, a spreadsheet, and hundreds of other
things, plus on-line documentation.  We hope to supply, eventually,
everything useful that normally comes with a Unix system, and more.

   GNU will be able to run Unix programs, but will not be identical to
Unix.  We will make all improvements that are convenient, based on our
experience with other operating systems.  In particular, we plan to
have longer file names, file version numbers, a crashproof file system,
file name completion perhaps, terminal-independent display support, and
perhaps eventually a Lisp-based window system through which several
Lisp programs and ordinary Unix programs can share a screen.  Both C
and Lisp will be available as system programming languages.  We will
try to support UUCP, MIT Chaosnet, and Internet protocols for
communication.

   GNU is aimed initially at machines in the 68000/16000 class with
virtual memory, because they are the easiest machines to make it run
on.  The extra effort to make it run on smaller machines will be left
to someone who wants to use it on them.

   To avoid horrible confusion, please pronounce the `G' in the word
`GNU' when it is the name of this project.

Why I Must Write GNU
====================

   I consider that the golden rule requires that if I like a program I
must share it with other people who like it.  Software sellers want to
divide the users and conquer them, making each user agree not to share
with others.  I refuse to break solidarity with other users in this
way.  I cannot in good conscience sign a nondisclosure agreement or a
software license agreement.  For years I worked within the Artificial
Intelligence Lab to resist such tendencies and other inhospitalities,
but eventually they had gone too far: I could not remain in an
institution where such things are done for me against my will.

   So that I can continue to use computers without dishonor, I have
decided to put together a sufficient body of free software so that I
will be able to get along without any software that is not free.  I
have resigned from the AI lab to deny MIT any legal excuse to prevent
me from giving GNU away.

Why GNU Will Be Compatible with Unix
====================================

   Unix is not my ideal system, but it is not too bad.  The essential
features of Unix seem to be good ones, and I think I can fill in what
Unix lacks without spoiling them.  And a system compatible with Unix
would be convenient for many other people to adopt.

How GNU Will Be Available
=========================

   GNU is not in the public domain.  Everyone will be permitted to
modify and redistribute GNU, but no distributor will be allowed to
restrict its further redistribution.  That is to say, proprietary
modifications will not be allowed.  I want to make sure that all
versions of GNU remain free.

Why Many Other Programmers Want to Help
=======================================

   I have found many other programmers who are excited about GNU and
want to help.

   Many programmers are unhappy about the commercialization of system
software.  It may enable them to make more money, but it requires them
to feel in conflict with other programmers in general rather than feel
as comrades.  The fundamental act of friendship among programmers is the
sharing of programs; marketing arrangements now typically used
essentially forbid programmers to treat others as friends.  The
purchaser of software must choose between friendship and obeying the
law.  Naturally, many decide that friendship is more important.  But
those who believe in law often do not feel at ease with either choice.
They become cynical and think that programming is just a way of making
money.

   By working on and using GNU rather than proprietary programs, we can
be hospitable to everyone and obey the law.  In addition, GNU serves as
an example to inspire and a banner to rally others to join us in
sharing.  This can give us a feeling of harmony which is impossible if
we use software that is not free.  For about half the programmers I
talk to, this is an important happiness that money cannot replace.

How You Can Contribute
======================

   I am asking computer manufacturers for donations of machines and
money.  I'm asking individuals for donations of programs and work.

   One consequence you can expect if you donate machines is that GNU
will run on them at an early date.  The machines should be complete,
ready to use systems, approved for use in a residential area, and not
in need of sophisticated cooling or power.

   I have found very many programmers eager to contribute part-time
work for GNU.  For most projects, such part-time distributed work would
be very hard to coordinate; the independently-written parts would not
work together.  But for the particular task of replacing Unix, this
problem is absent.  A complete Unix system contains hundreds of utility
programs, each of which is documented separately.  Most interface
specifications are fixed by Unix compatibility.  If each contributor
can write a compatible replacement for a single Unix utility, and make
it work properly in place of the original on a Unix system, then these
utilities will work right when put together.  Even allowing for Murphy
to create a few unexpected problems, assembling these components will
be a feasible task.  (The kernel will require closer communication and
will be worked on by a small, tight group.)

   If I get donations of money, I may be able to hire a few people full
or part time.  The salary won't be high by programmers' standards, but
I'm looking for people for whom building community spirit is as
important as making money.  I view this as a way of enabling dedicated
people to devote their full energies to working on GNU by sparing them
the need to make a living in another way.

Why All Computer Users Will Benefit
===================================

   Once GNU is written, everyone will be able to obtain good system
software free, just like air.(2)

   This means much more than just saving everyone the price of a Unix
license.  It means that much wasteful duplication of system programming
effort will be avoided.  This effort can go instead into advancing the
state of the art.

   Complete system sources will be available to everyone.  As a result,
a user who needs changes in the system will always be free to make them
himself, or hire any available programmer or company to make them for
him.  Users will no longer be at the mercy of one programmer or company
which owns the sources and is in sole position to make changes.

   Schools will be able to provide a much more educational environment
by encouraging all students to study and improve the system code.
Harvard's computer lab used to have the policy that no program could be
installed on the system if its sources were not on public display, and
upheld it by actually refusing to install certain programs.  I was very
much inspired by this.

   Finally, the overhead of considering who owns the system software
and what one is or is not entitled to do with it will be lifted.

   Arrangements to make people pay for using a program, including
licensing of copies, always incur a tremendous cost to society through
the cumbersome mechanisms necessary to figure out how much (that is,
which programs) a person must pay for.  And only a police state can
force everyone to obey them.  Consider a space station where air must
be manufactured at great cost: charging each breather per liter of air
may be fair, but wearing the metered gas mask all day and all night is
intolerable even if everyone can afford to pay the air bill.  And the
TV cameras everywhere to see if you ever take the mask off are
outrageous.  It's better to support the air plant with a head tax and
chuck the masks.

   Copying all or parts of a program is as natural to a programmer as
breathing, and as productive.  It ought to be as free.

Some Easily Rebutted Objections to GNU's Goals
==============================================

     "Nobody will use it if it is free, because that means they can't
     rely on any support."

     "You have to charge for the program to pay for providing the
     support."

   If people would rather pay for GNU plus service than get GNU free
without service, a company to provide just service to people who have
obtained GNU free ought to be profitable.(3)

   We must distinguish between support in the form of real programming
work and mere handholding.  The former is something one cannot rely on
from a software vendor.  If your problem is not shared by enough
people, the vendor will tell you to get lost.

   If your business needs to be able to rely on support, the only way
is to have all the necessary sources and tools.  Then you can hire any
available person to fix your problem; you are not at the mercy of any
individual.  With Unix, the price of sources puts this out of
consideration for most businesses.  With GNU this will be easy.  It is
still possible for there to be no available competent person, but this
problem cannot be blamed on distribution arrangements.  GNU does not
eliminate all the world's problems, only some of them.

   Meanwhile, the users who know nothing about computers need
handholding: doing things for them which they could easily do
themselves but don't know how.

   Such services could be provided by companies that sell just
hand-holding and repair service.  If it is true that users would rather
spend money and get a product with service, they will also be willing
to buy the service having got the product free.  The service companies
will compete in quality and price; users will not be tied to any
particular one.  Meanwhile, those of us who don't need the service
should be able to use the program without paying for the service.

     "You cannot reach many people without advertising, and you must
     charge for the program to support that."

     "It's no use advertising a program people can get free."

   There are various forms of free or very cheap publicity that can be
used to inform numbers of computer users about something like GNU.  But
it may be true that one can reach more microcomputer users with
advertising.  If this is really so, a business which advertises the
service of copying and mailing GNU for a fee ought to be successful
enough to pay for its advertising and more.  This way, only the users
who benefit from the advertising pay for it.

   On the other hand, if many people get GNU from their friends, and
such companies don't succeed, this will show that advertising was not
really necessary to spread GNU.  Why is it that free market advocates
don't want to let the free market decide this?(4)

     "My company needs a proprietary operating system to get a
     competitive edge."

   GNU will remove operating system software from the realm of
competition.  You will not be able to get an edge in this area, but
neither will your competitors be able to get an edge over you.  You and
they will compete in other areas, while benefiting mutually in this
one.  If your business is selling an operating system, you will not
like GNU, but that's tough on you.  If your business is something else,
GNU can save you from being pushed into the expensive business of
selling operating systems.

   I would like to see GNU development supported by gifts from many
manufacturers and users, reducing the cost to each.(5)

     "Don't programmers deserve a reward for their creativity?"

   If anything deserves a reward, it is social contribution.
Creativity can be a social contribution, but only in so far as society
is free to use the results.  If programmers deserve to be rewarded for
creating innovative programs, by the same token they deserve to be
punished if they restrict the use of these programs.

     "Shouldn't a programmer be able to ask for a reward for his
     creativity?"

   There is nothing wrong with wanting pay for work, or seeking to
maximize one's income, as long as one does not use means that are
destructive.  But the means customary in the field of software today
are based on destruction.

   Extracting money from users of a program by restricting their use of
it is destructive because the restrictions reduce the amount and the
ways that the program can be used.  This reduces the amount of wealth
that humanity derives from the program.  When there is a deliberate
choice to restrict, the harmful consequences are deliberate destruction.

   The reason a good citizen does not use such destructive means to
become wealthier is that, if everyone did so, we would all become
poorer from the mutual destructiveness.  This is Kantian ethics; or,
the Golden Rule.  Since I do not like the consequences that result if
everyone hoards information, I am required to consider it wrong for one
to do so.  Specifically, the desire to be rewarded for one's creativity
does not justify depriving the world in general of all or part of that
creativity.

     "Won't programmers starve?"

   I could answer that nobody is forced to be a programmer.  Most of us
cannot manage to get any money for standing on the street and making
faces.  But we are not, as a result, condemned to spend our lives
standing on the street making faces, and starving.  We do something
else.

   But that is the wrong answer because it accepts the questioner's
implicit assumption: that without ownership of software, programmers
cannot possibly be paid a cent.  Supposedly it is all or nothing.

   The real reason programmers will not starve is that it will still be
possible for them to get paid for programming; just not paid as much as
now.

   Restricting copying is not the only basis for business in software.
It is the most common basis because it brings in the most money.  If it
were prohibited, or rejected by the customer, software business would
move to other bases of organization which are now used less often.
There are always numerous ways to organize any kind of business.

   Probably programming will not be as lucrative on the new basis as it
is now.  But that is not an argument against the change.  It is not
considered an injustice that sales clerks make the salaries that they
now do.  If programmers made the same, that would not be an injustice
either.  (In practice they would still make considerably more than
that.)

     "Don't people have a right to control how their creativity is
     used?"

   "Control over the use of one's ideas" really constitutes control over
other people's lives; and it is usually used to make their lives more
difficult.

   People who have studied the issue of intellectual property rights
carefully (such as lawyers) say that there is no intrinsic right to
intellectual property.  The kinds of supposed intellectual property
rights that the government recognizes were created by specific acts of
legislation for specific purposes.

   For example, the patent system was established to encourage
inventors to disclose the details of their inventions.  Its purpose was
to help society rather than to help inventors.  At the time, the life
span of 17 years for a patent was short compared with the rate of
advance of the state of the art.  Since patents are an issue only among
manufacturers, for whom the cost and effort of a license agreement are
small compared with setting up production, the patents often do not do
much harm.  They do not obstruct most individuals who use patented
products.

   The idea of copyright did not exist in ancient times, when authors
frequently copied other authors at length in works of non-fiction.  This
practice was useful, and is the only way many authors' works have
survived even in part.  The copyright system was created expressly for
the purpose of encouraging authorship.  In the domain for which it was
invented--books, which could be copied economically only on a printing
press--it did little harm, and did not obstruct most of the individuals
who read the books.

   All intellectual property rights are just licenses granted by society
because it was thought, rightly or wrongly, that society as a whole
would benefit by granting them.  But in any particular situation, we
have to ask: are we really better off granting such license?  What kind
of act are we licensing a person to do?

   The case of programs today is very different from that of books a
hundred years ago.  The fact that the easiest way to copy a program is
from one neighbor to another, the fact that a program has both source
code and object code which are distinct, and the fact that a program is
used rather than read and enjoyed, combine to create a situation in
which a person who enforces a copyright is harming society as a whole
both materially and spiritually; in which a person should not do so
regardless of whether the law enables him to.

     "Competition makes things get done better."

   The paradigm of competition is a race: by rewarding the winner, we
encourage everyone to run faster.  When capitalism really works this
way, it does a good job; but its defenders are wrong in assuming it
always works this way.  If the runners forget why the reward is offered
and become intent on winning, no matter how, they may find other
strategies--such as, attacking other runners.  If the runners get into
a fist fight, they will all finish late.

   Proprietary and secret software is the moral equivalent of runners
in a fist fight.  Sad to say, the only referee we've got does not seem
to object to fights; he just regulates them ("For every ten yards you
run, you can fire one shot").  He really ought to break them up, and
penalize runners for even trying to fight.

     "Won't everyone stop programming without a monetary incentive?"

   Actually, many people will program with absolutely no monetary
incentive.  Programming has an irresistible fascination for some
people, usually the people who are best at it.  There is no shortage of
professional musicians who keep at it even though they have no hope of
making a living that way.

   But really this question, though commonly asked, is not appropriate
to the situation.  Pay for programmers will not disappear, only become
less.  So the right question is, will anyone program with a reduced
monetary incentive?  My experience shows that they will.

   For more than ten years, many of the world's best programmers worked
at the Artificial Intelligence Lab for far less money than they could
have had anywhere else.  They got many kinds of non-monetary rewards:
fame and appreciation, for example.  And creativity is also fun, a
reward in itself.

   Then most of them left when offered a chance to do the same
interesting work for a lot of money.

   What the facts show is that people will program for reasons other
than riches; but if given a chance to make a lot of money as well, they
will come to expect and demand it.  Low-paying organizations do poorly
in competition with high-paying ones, but they do not have to do badly
if the high-paying ones are banned.

     "We need the programmers desperately.  If they demand that we stop
     helping our neighbors, we have to obey."

   You're never so desperate that you have to obey this sort of demand.
Remember: millions for defense, but not a cent for tribute!

     "Programmers need to make a living somehow."

   In the short run, this is true.  However, there are plenty of ways
that programmers could make a living without selling the right to use a
program.  This way is customary now because it brings programmers and
businessmen the most money, not because it is the only way to make a
living.  It is easy to find other ways if you want to find them.  Here
are a number of examples.

   A manufacturer introducing a new computer will pay for the porting of
operating systems onto the new hardware.

   The sale of teaching, hand-holding and maintenance services could
also employ programmers.

   People with new ideas could distribute programs as freeware, asking
for donations from satisfied users, or selling hand-holding services.
I have met people who are already working this way successfully.

   Users with related needs can form users' groups, and pay dues.  A
group would contract with programming companies to write programs that
the group's members would like to use.

   All sorts of development can be funded with a Software Tax:

     Suppose everyone who buys a computer has to pay x percent of the
     price as a software tax.  The government gives this to an agency
     like the NSF to spend on software development.

     But if the computer buyer makes a donation to software development
     himself, he can take a credit against the tax.  He can donate to
     the project of his own choosing--often, chosen because he hopes to
     use the results when it is done.  He can take a credit for any
     amount of donation up to the total tax he had to pay.

     The total tax rate could be decided by a vote of the payers of the
     tax, weighted according to the amount they will be taxed on.

     The consequences:

        * The computer-using community supports software development.

        * This community decides what level of support is needed.

        * Users who care which projects their share is spent on can
          choose this for themselves.

   In the long run, making programs free is a step toward the
post-scarcity world, where nobody will have to work very hard just to
make a living.  People will be free to devote themselves to activities
that are fun, such as programming, after spending the necessary ten
hours a week on required tasks such as legislation, family counseling,
robot repair and asteroid prospecting.  There will be no need to be
able to make a living from programming.

   We have already greatly reduced the amount of work that the whole
society must do for its actual productivity, but only a little of this
has translated itself into leisure for workers because much
nonproductive activity is required to accompany productive activity.
The main causes of this are bureaucracy and isometric struggles against
competition.  Free software will greatly reduce these drains in the
area of software production.  We must do this, in order for technical
gains in productivity to translate into less work for us.

   ---------- Footnotes ----------

   (1)  The wording here was careless.  The intention was that nobody
would have to pay for *permission* to use the GNU system.  But the
words don't make this clear, and people often interpret them as saying
that copies of GNU should always be distributed at little or no charge.
That was never the intent; later on, the manifesto mentions the
possibility of companies providing the service of distribution for a
profit.  Subsequently I have learned to distinguish carefully between
"free" in the sense of freedom and "free" in the sense of price.  Free
software is software that users have the freedom to distribute and
change.  Some users may obtain copies at no charge, while others pay to
obtain copies--and if the funds help support improving the software, so
much the better.  The important thing is that everyone who has a copy
has the freedom to cooperate with others in using it.

   (2)  This is another place I failed to distinguish carefully between
the two different meanings of "free".  The statement as it stands is
not false--you can get copies of GNU software at no charge, from your
friends or over the net.  But it does suggest the wrong idea.

   (3)  Several such companies now exist.

   (4)  The Free Software Foundation raises most of its funds from a
distribution service, although it is a charity rather than a company.
If *no one* chooses to obtain copies by ordering from the FSF, it will
be unable to do its work.  But this does not mean that proprietary
restrictions are justified to force every user to pay.  If a small
fraction of all the users order copies from the FSF, that is sufficient
to keep the FSF afloat.  So we ask users to choose to support us in
this way.  Have you done your part?

   (5)  A group of computer companies recently pooled funds to support
maintenance of the GNU C Compiler.


File: ^.!gcc.docs.pascal.gpc,  Node: Purpose,  Next: Installation,  Prev: Manifesto,  Up: Top

The Purpose of GNU Pascal
*************************

   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 normal 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.

   GNU Pascal compiler is part of the GNU Compiler family combining a
language independent part of the GNU Compiler with a Pascal specific
front end.

   Other compilers of the family currently include compilers for the C,
C++ and Objective C languages.


File: ^.!gcc.docs.pascal.gpc,  Node: Installation,  Next: Invoking GPC,  Prev: Purpose,  Up: Top

Installing GNU Pascal
*********************

   This chapter covers:
   * Installation instructions for a GPC binary distribution

   * Compilation of the source distribution on a UNIX system

   * Problems

   The preferred way to distribute GNU software is distribution of the
source code.  However it is nontrivial to compile GNU Pascal on non-UNIX
systems, so we also provide ready-to-run binaries for the following
platforms:

   * DJGPP for DOS (you need DJGPP v2.0 installed),

   * EMX for DOS and OS/2 (you need the EMX extender),

   * cygwin32 for Windows 95/NT, and

   * Linux.

   To install a binary distribution, cd to the main directory and
unpack the archive while preserving the stored directory structure.  In
concrete, to install a ZIP archive under DOS with PKunzip, type

       C:\> pkunzip -d ARCHIVE

   where ARCHIVE is the name of the distribution file.  To install a
TGZ archive under Linux, become root, then extract the archive from the
root of the filesystem:

       # tar xzf ARCHIVE.tar.gz

   Binary distributions include `libgcc.' and `specs', files that are
normally part of gcc. If you have gcc installed, they will be replaced
unless you manually install the archive.

   Compilation instructions for the different platforms and more about
the extenders mentioned above follow.

* Menu:

* UNIX::            Installation on a UNIX system
* DOS: DJGPP.       The DJGPP port of GNU compilers to MS-DOS
* DOS, OS/2: EMX.   The EMX port of GNU compilers to MS-DOS and OS/2
* Win32::           Installation on a Windows 95/NT system
* Cross-Compiler::  Building and installing a cross-compiler.


File: ^.!gcc.docs.pascal.gpc,  Node: UNIX,  Next: DJGPP,  Up: Installation

Installation on a UNIX system
=============================

   GPC is based on GNU CC; you will need the GCC sources to build it.
It must be the same version as the one GPC is implemented with.
Although you need GCC to build the GNU Pascal compiler, you don't need
GCC to compile Pascal programs once GNU Pascal is installed.

   Here is the generic procedure for installing GNU Pascal on a Unix
system.  See *Note System V:: for System V compatible unices (e.g.
Linux), *Note Alpha OSF/1:: for Alpha OSF/1 systems.

  1. Unpack source distributions.

     Sources for GNU CC and GNU Pascal must be unpacked in separate
     directories.  It is possible, though not required, to build the
     compiler(s) in a directory other than the one containing the
     sources. In either case, you need a `make' that understands the
     VPATH variable. GNU make does, although at least GNU make version
     3.71 has a bug in the way it treats VPATH.  GNU make version 3.74
     is known to work.

     XREF See the section problems.

     If you have built GNU Pascal previously in the same directory for a
     different target machine, do `make distclean' to delete all files
     that might be invalid.  One of the files this deletes is
     `Makefile'; if `make distclean' complains that `Makefile' does not
     exist, it probably means that the directory is already suitably
     clean.

  2. Configure and build GNU CC Chdir to the GCC object directory and
     configure GCC. Configuration of GNU CC is treated in depth in
     Chapter 4 of "Using and Porting GNU CC" Usually,

          % ../gcc/configure --prefix=/usr

     will do the job. This creates all the necessary config files,
     links and Makefile in the GCC object directory.

  3. The standard directory for installing GNU CC and GNU Pascal is
     `/usr/local/lib'. If you want to install its files somewhere else,
     specify `--prefix=DIR' when you run `configure'.  Here DIR is a
     directory name to use instead of `/usr/local' for all purposes
     with one exception: the directory `/usr/local/include' is searched
     for header files no matter where you install the compiler.  To
     override this name, use the `--local-prefix' option below.

  4. Specify `--local-prefix=DIR' if you want the compiler to search
     directory `DIR/include' for locally installed header files
     *instead* of `/usr/local/include'.

     You should specify `--local-prefix' *only* if your site has a
     different convention (not `/usr/local') for where to put
     site-specific files.

     *Do not* specify `/usr' as the `--local-prefix'!  The directory
     you use for `--local-prefix' *must not* contain any of the
     system's standard header files.  If it did contain them, certain
     programs would be miscompiled (including GNU Emacs, on certain
     targets), because this would override and nullify the header file
     corrections made by the `fixincludes' script.

  5. Make sure the Bison parser generator is installed.  (This is
     unnecessary if the Bison output files `c-parse.c' and `cexp.c' are
     more recent than `c-parse.y' and `cexp.y' and you do not plan to
     change the `.y' files.)

     Bison versions older than Sept 8, 1988 will produce incorrect
     output for `c-parse.c'.

  6. If you have chosen a configuration for GNU Pascal which requires
     other GNU tools (such as GAS or the GNU linker) instead of the
     standard system tools, install the required tools in the build
     directory under the names `as', `ld' or whatever is appropriate.
     This will enable the compiler to find the proper tools for
     compilation of the program `enquire'.

     Alternatively, you can do subsequent compilation using a value of
     the `PATH' environment variable such that the necessary GNU tools
     come before the standard system tools.

  7. Build the C compiler:

          % make LANGUAGES=c

     (Just `make' would also build the C++ and Objective C compilers).
     You do not need to install the compiler you just built, but leave
     the objects in place, since GPC will directly load most of the GCC
     object files.

  8. Configure GNU Pascal for your system.  Normally, you just `cd' to
     the directory containing the source code and type `./configure'.
     If you're using `csh' on an old version of System V, you might
     need to type `sh configure' instead to prevent `csh' from trying
     to execute `configure' itself (under AIX, you may need to use ksh
     instead of sh).

     To compile the GNU Pascal in a different directory from the one
     containing the source code, `cd' to the directory where you want
     the object files and executables to go and run the `configure'
     script.  `configure' automatically checks for the source code in
     the directory that `configure' is in. If for some reason
     `configure' is not able to find the source directory, rerun
     `configure' with the option `--srcdir=DIR', where DIR is the
     directory that contains the source code.

     Note that the gpc `configure' script does not accept most of the
     switches usually given to a `configure' script because is gets
     this information from the GCC configuration files.

     Running `configure' takes a while.  While it is running, it prints
     some messages that tell what it is doing.  If you don't want to
     see any messages, run `configure' with its standard output
     redirected to /dev/null; for example, `./configure >/dev/null'.

     If `configure' is unable to locate GNU CC sources or object code,
     it will print an error message and exit. In that case, run
     `configure' again with `--with-gccsrc=DIR' and / or
     `--with-gccbin=DIR' arguments.

     When it is finished, `configure' prints a short summary of the
     information it has collected.

          Configuration summary:
            GCC version:          2.7.2
            GCC sources in:       ../gcc-2.7.2
            GCC object code in:   ../gcc-i486-linux
            GPC sources in:       .
            Installation path:    /usr/bin, /usr/lib/gcc-lib/i486-linux/2.7.2
            Compiler:             gcc
            Compiler flags:       -g -O
            RTS compiler:         gcc

          Now, type "make" to build the compiler and runtime system.

  9. Building the compiler.  Once you are satisfied with the
     configuration as determined by `configure', you can build the
     compiler:

          make

     Optionally, you may supply CFLAGS, LDFLAGS or RTSFLAGS. CFLAGS is
     used for compiler and RTS, RTSFLAGS are   for RTS only, i.e.:
     'make CFLAGS="-m486 -O2" RTSFLAGS=-Wall'

 10. When everything compiles, you can verify what the  `make -n
     install' command does, and if you are satisfied run it without the
     `-n' option to install the compiler (gpc1), front end (gpc), run
     time system (libgpc.a) to the same place where gcc was installed.

     It is sort of stupid to have a separate incarnation of `gcc.c'; the
     difference now is that "gpc" also searches from library `libgpc.a'
     and `-lm'. In addition `gcc.c' specifies the interface to the
     Pascal compiler (gpc1). This command will vanish when "gcc" knows
     how to compile Pascal programs.


   Configuration dependent notes:

* Menu:

* System V::        Installation on System V comptaible unices (e.g. Linux)
* Alpha OSF/1::     Installation on an Alpha OSF/1 system


File: ^.!gcc.docs.pascal.gpc,  Node: System V,  Next: Alpha OSF/1,  Up: UNIX

System V compatible unices (e.g. Linux)
---------------------------------------

   Compiling the Runtime System (RTS) on a System V compatible unix
requires "-DSYSV" to be set in CFLAGS. `configure' recognizes a number
of System V compatible unices, but not all.

   If you see:
     ../srcdir/rts/rts-rt0.c: In function `_p_initialize':
     ../srcdir/rts/rts-rt0.c:286: `SIGEMT' undeclared (first use this function)
     ../srcdir/rts/rts-rt0.c:290: `SIGSYS' undeclared (first use this function)
   while building `libgpc.a', you have to add "-DSYSV" to your
MY_CFLAGS.

   Example:
     % make MY_CFLAGS=-DSYSV other-make-flags-you-want-to-use

   Please send a report, with the canonical name of the system to
`[e-mail]'


File: ^.!gcc.docs.pascal.gpc,  Node: Alpha OSF/1,  Prev: System V,  Up: UNIX

Alpha OSF/1
-----------

   For alpha OSF/1 v3.2 (GCC 2.6.3): If your linker starts to output
error messages like:

     Warning: Linking some objects which contain exception information sections
         and some which do not. This may cause fatal runtime exception handling
         problems (last obj encountered without exceptions was <OBJ/LIB>)

   I do not know why these started to appear, but you can get rid of
these if you do as follows in the GPC object directory.

   You need to trigger the Makefile dependencies, e.g. by doing the
touch command below. What happens is that it re-generates the version.c
and rts/version.c files, which need to be recompiled with `ALPHA_BUG'
defined.

   Example:
     % touch Makefile
     % make MY_CFLAGS=-DALPHA_BUG other-make-flags-you-want-to-use


File: ^.!gcc.docs.pascal.gpc,  Node: DJGPP,  Next: EMX,  Prev: UNIX,  Up: Installation

GNU Pascal for MS-DOS with DJGPP
================================

   You cannot build GNU CC (or GNU Pascal) by itself on MS-DOS; it will
not compile under any MS-DOS compiler except itself. The official
MS-DOS port of GCC is called djgpp, and it is available from
`simtel.coast.net' and it's mirrors all over the world. The `configure'
script is replaced by an MS-DOS batch file called `configure.bat' wich
does essentially the same. A pre-configured source distribution should
be available from the same site where you got djgpp.


File: ^.!gcc.docs.pascal.gpc,  Node: EMX,  Next: Win32,  Prev: DJGPP,  Up: Installation

GNU Pascal for MS-DOS or OS/2 with EMX
======================================

   EMX is a FreeWare 32-bit DOS extender which adds some properties of
UNIX to the DOS and OS/2 operating systems written by Eberhard Mattes.
You can find it, for example, via anonymous `ftp' on the server
`ftp.uni-stuttgart.de' in the directory `pub/systems/os2/emx*'.

   The EMX extender for DOS and OS/2 makes it relatively easy to port
GNU tools--such as the GNU Pascal Compiler--to these platforms.
However, it is not straightforward to compile it.  There is no bash.
No symbolic links.  8.3 file names.  Etc.  It took me about two
complete days to find out what to do--not much when facing the about 15
MegaBytes of sources, but enough.  The method I finally did it through
might be not the best one but it works, and I document it here.  If
somebody finds a cleaner way how to compile GNU Pascal for EMX, please
let me know!  `<[e-mail]>'.

  0. I assume you have the EMX package installed with GNU development
     tools and the `nmake' make utility.

     If you are using a DOS system, you are in trouble now, because the
     required utility `nmake' is an OS/2 program.  I was not able to
     replace it with, for example, Borland `make'; if you are, please
     inform me.

  1. Get the patched source code GCCSRC1.ZIP, GCCSRC2.ZIP, GCCSRC3.ZIP
     for GCC version 2.7.2.  (The correct version is important.)  Get
     the original source ZIP archive for GNU Pascal (GPC) 2.7.2 from
     `kampi.hut.fi'.

  2. Unzip the source for GCC.  E.g. with PKUNZIP, when the ZIP files
     are in the `C:\' directory:

            pkunzip -d c:\gccsrc? \

  3. Unzip the source for GPC in the `emx\gnu' directory.

            cd \emx\gnu
            pkunzip -d c:\gpc-272

  4. Rename the GCC subdirectory in `\emx\gnu' to make things more
     symmetric. (-: Don't omit this because the Makefile I created
     relies on this naming.)

            rendir gcc-2.7 gcc-272

     (with OS/2: `ren')

  5. Cd to the EMX subdirectory and run the nmake utility telling it
     whether you are using a FAT or a HPFS partition.  Use UPPERCASE
     here--nmake is case-sensitive.

            cd gpc-272\emx
            nmake FS=FAT

     Be patient - this will take a while to complete.

  6. That's it.  Hope that not too much went wrong.  Write some tiny
     test programs.  Write useful larger programs with GPC ...


File: ^.!gcc.docs.pascal.gpc,  Node: Win32,  Next: Cross-Compiler,  Prev: EMX,  Up: Installation

GNU Pascal for Windows NT and Windows 95 with CygWin32
======================================================

   CygWin32 is a project to make it easy to port Unix applications to
machines which run an OS which supports the Win32 API - ie Windows 95
and Windows NT.  Windows NT runs on more than just the 386 too.
Currently, cygwin32 is in beta stage; it is available from
`ftp://ftp.cygnus.com/pub/gnu-win32/' This (beta) GCC is incompatible
with GNU Pascal, but neither gcc-2.6.3 nor gcc-2.7.2 does support the
cygwin32 platform. To patch cygwin32 support into a regular GNU CC
distribution, you need a special patch, available from the site where
you got the GNU Pascal sources. Because of the unix-ish environment
provided by cygwin32, configuring and building GNU Pascal is
essentially the same as a unix configuration.

   Currently, GNU Pascal does not support the stack calling convention
of the Win32 API, thus making it impossible to access system DLL's.


File: ^.!gcc.docs.pascal.gpc,  Node: Cross-Compiler,  Prev: Win32,  Up: Installation

Building and Installing a Cross-Compiler
========================================

   GNU Pascal can function as a cross-compiler for many machines, but
not all.  Also, only a few combinations have been tested. If you need
information about GNU tools in a cross-configuration,
`ftp://ftp.cygnus.com/pub/embedded/crossgcc/' is the place to be.

   * Cross-compilers for the Mips as target using the Mips assembler
     currently do not work, because the auxiliary programs
     `mips-tdump.c' and `mips-tfile.c' can't be compiled on anything
     but a Mips.  It does work to cross compile for a Mips if you use
     the GNU assembler and linker.

   * Cross-compilers between machines with different floating point
     formats have not all been made to work.  GNU C now has a floating
     point emulator with which these can work, but each target machine
     description needs to be updated to take advantage of it.

   * Cross-compilation between machines of different word sizes is
     somewhat problematic and sometimes does not work.

   Since GNU Pascal generates assembler code, you probably need a
cross-assembler that GNU Pascal can run, in order to produce object
files.  If you want to link on other than the target machine, you need a
cross-linker as well.  You also need header files and libraries suitable
for the target machine that you can install on the host machine.

* Menu:

* Steps of Cross::      Using a cross-compiler involves several steps
                        that may be carried out on different machines.
* Configure Cross::     Configuring a cross-compiler.
* Build Cross::         Actually building a Pascal cross-compiler.


File: ^.!gcc.docs.pascal.gpc,  Node: Steps of Cross,  Next: Configure Cross,  Up: Cross-Compiler

Steps of Cross-Compilation
--------------------------

   To compile and run a program using a cross-compiler involves several
steps:

   * Run the cross-compiler on the host machine to produce assembler
     files for the target machine.  This requires header files for the
     target machine.

   * Assemble the files produced by the cross-compiler.  You can do this
     either with an assembler on the target machine, or with a
     cross-assembler on the host machine.

   * Link those files to make an executable.  You can do this either
     with a linker on the target machine, or with a cross-linker on the
     host machine.  Whichever machine you use, you need libraries and
     certain startup files (typically `crt....o') for the target
     machine.

   It is most convenient to do all of these steps on the same host
machine, since then you can do it all with a single invocation of GNU
Pascal.  This requires a suitable cross-assembler and cross-linker.
For some targets, the GNU assembler and linker are available.


File: ^.!gcc.docs.pascal.gpc,  Node: Configure Cross,  Next: Build Cross,  Prev: Steps of Cross,  Up: Cross-Compiler

Configuring GNU CC as a Cross-Compiler
--------------------------------------

   No special actions have to be taken to configure GNU Pascal as a
crosscompiler. Cross-compiler specific configuration is done only for
GCC.  Section 4.2 of "Using and Porting GNU CC" deals with
cross-configurations in great detail. Once cross-binutils and a C
library for the target machine are in place, GCC can be configured
(from the GCC object directory).  Suppose we are on a Linux system and
want a cross-compiler that produces code that runs on MS-DOS:

     % ../gcc/configure --prefix=/usr --target=i386-go32

   This creates all the necessary config files, links and Makefile in
the GCC object directory. Now, proceed with the compilation and
installation process like in the case of the native configuration
described before. Do not remove files from the GCC object directory;
the cross-compiler is used to compile the GNU Pascal runtime system
(RTS) for the target system.


File: ^.!gcc.docs.pascal.gpc,  Node: Build Cross,  Prev: Configure Cross,  Up: Cross-Compiler

Building the Pascal Cross-Compiler
----------------------------------

   Once you have verified the C cross-compiler, the Pascal
cross-compiler can be configured and built. Note that the `configure'
script does not require any cross-compiler related switches because GPC
inherits all of this from GNU CC.  Assuming GCC object code is in
`../gcc-i386-go32/',

     % ../gpc/configure --srcdir=../gpc --gccdir=../gcc-i386-go32 --gccsrc=../gcc
     % make

   Then, "make install" the cross-compiler.


File: ^.!gcc.docs.pascal.gpc,  Node: Invoking GPC,  Next: Keywords,  Prev: Installation,  Up: Top

GNU Pascal Command Options
**************************

   When you invoke GPC, it normally does preprocessing, compilation,
assembly and linking.  The "overall options" allow you to stop this
process at an intermediate stage.  For example, the `-c' option says
not to run the linker.  Then the output consists of object files output
by the assembler.

   Other options are passed on to one stage of processing.  Some options
control the preprocessor and others the compiler itself.  Yet other
options control the assembler and linker; most of these are not
documented here, since you rarely need to use any of them.

   The `gpc' program accepts options and file names as operands.  Many
options have multiletter names; therefore multiple single-letter options
may *not* be grouped: `-dr' is very different from `-d -r'.

   You can mix options and other arguments.  For the most part, the
order you use doesn't matter.  Order does matter when you use several
options of the same kind; for example, if you specify `-L' more than
once, the directories are searched in the order specified.

   Many options have long names starting with `-f' or with `-W'--for
example, `-fforce-mem', `-fstrength-reduce', `-Wformat' and so on.
Most of these have both positive and negative forms; the negative form
of `-ffoo' would be `-fno-foo'.  This manual documents only one of
these two forms, whichever one is not the default.

* Menu:

* Option Summary::          Brief list of all options, without explanations.
* Overall Options::        Controlling the kind of output:
                           an executable, object files, assembler files,
                           or preprocessed source.
* Pascal Dialect Options:: Controlling the variant of Pascal language compiled.
* Code Gen Options::       Specifying conventions for function calls, data
                           layout and register usage.
* Warning Options::        How picky should the compiler be?
* Debugging Options::      Symbol tables, measurements, and debugging dumps.
* Optimize Options::       How much optimization?
* Preprocessor Options::   Controlling header files and macro definitions.
                           Also, getting dependency information for Make.
* Assembler Options::      Passing options to the assembler.
* Link Options::           Specifying libraries and so on.
* Directory Options::      Where to find header files and libraries.
                           Where to find the compiler executable files.
* Target Options::         Running a cross-compiler, or an old version
                           of GNU Pascal.
* Submodel Options::       Specifying minor hardware or convention variations,
                           such as 68010 vs 68020.
* Environment Variables::  Env vars that affect GNU Pascal.


File: ^.!gcc.docs.pascal.gpc,  Node: Option Summary,  Next: Overall Options,  Up: Invoking GPC

Option Summary
==============

   Here is a summary of all the options, grouped by type.  Explanations
are in the following sections.

*Overall Options*
     *Note Options Controlling the Kind of Output: Overall Options.
          -c  --automake  -S  -E  -o FILE  -pipe  -v  -x LANGUAGE

*Pascal Language Options*
     *Note Options Controlling Pascal Dialect: Pascal Dialect Options.
          --nested-comments --char-escapes --c-numbers
          --standard-pascal --extended-pascal --object-pascal --borland-pascal
          --pascal-sc --extended-syntax

*Code Generation Options*
     *Note Options for Code Generation Conventions: Code Gen Options.
          --short-circuit --lazy-io --setlimit
          --call-saved-REG  --call-used-REG
          --fixed-REG  --inhibit-size-directive
          --no-common  --no-ident  --no-gnu-linker
          --pcc-struct-return  --pic  --PIC
          --reg-struct-return  --shared-data  --short-enums
          --short-double  --volatile  --volatile-global
          --verbose-asm --pack-struct

*Warning Options*
     *Note Options to Request or Suppress Warnings: Warning Options.
          --syntax-only  --pedantic  --pedantic-errors
          -w  -W  -Wall  -Waggregate-return  -Wbad-function-cast
          -Wcast-align -Wcast-qual  -Wchar-subscript  -Wcomment
          -Wconversion -Wenum-clash  -Werror  -Wformat
          -Wid-clash-LEN  -Wimplicit  -Wimport  -Winline
          -Wlarger-than-LEN  -Wmissing-declarations
          -Wmissing-prototypes  -Wnested-externs
          -Wno-import  -Woverloaded-virtual -Wparentheses
          -Wpointer-arith  -Wredundant-decls -Wreorder -Wreturn-type -Wshadow
          -Wstrict-prototypes  -Wswitch  -Wsynth  -Wtemplate-debugging
          -Wtraditional  -Wtrigraphs -Wuninitialized  -Wunused
          -Wwrite-strings

*Debugging Options*
     *Note Options for Debugging Your Program or GCC: Debugging Options.
          -a  -dLETTERS  -fpretend-float
          -g  -gLEVEL -gcoff  -gdwarf  -gdwarf+
          -ggdb  -gstabs  -gstabs+  -gxcoff  -gxcoff+
          -p  -pg  -print-file-name=LIBRARY  -print-libgcc-file-name
          -print-prog-name=PROGRAM  -print-search-dirs  -save-temps
          --lines  --debug-gpi

*Optimization Options*
     *Note Options that Control Optimization: Optimize Options.
          --caller-saves  --cse-follow-jumps  --cse-skip-blocks
          --delayed-branch   --expensive-optimizations
          --fast-math  --float-store  --force-addr  --force-mem
          --inline-functions  --keep-inline-functions
          --no-default-inline  --no-defer-pop  --no-function-cse
          --no-inline  --no-peephole  --omit-frame-pointer
          --rerun-cse-after-loop  --schedule-insns
          --schedule-insns2  --strength-reduce  --thread-jumps
          --unroll-all-loops  --unroll-loops
          -O  -O0  -O1  -O2  -O3

*Preprocessor Options*
     *Note Options Controlling the Preprocessor: Preprocessor Options.
          -AQUESTION(ANSWER)  -C  -dD  -dM  -dN
          -DMACRO[=DEFN]  -E  -H
          -idirafter DIR
          -include FILE  -imacros FILE
          -iprefix FILE  -iwithprefix DIR
          -iwithprefixbefore DIR  -isystem DIR
          -M  -MD  -MM  -MMD  -MG  -nostdinc  -P  -trigraphs
          -undef  -UMACRO  -Wp,OPTION

*Assembler Option*
     *Note Passing Options to the Assembler: Assembler Options.
          -Wa,OPTION

*Linker Options*
     *Note Options for Linking: Link Options.
          OBJECT-FILE-NAME  -lLIBRARY
          -nostartfiles  -nodefaultlibs  -nostdlib
          -s  -static  -shared  -symbolic
          -Wl,OPTION  -Xlinker OPTION
          -u SYMBOL

*Directory Options*
     *Note Options for Directory Search: Directory Options.
          -BPREFIX  -IDIR  -I-  -LDIR

*Target Options*
     *Note Target Options::.
          -b MACHINE  -V VERSION

*Machine Dependent Options*
     *Note Hardware Models and Configurations: Submodel Options.
          *M680x0 Options*
          -m68000  -m68020  -m68020-40  -m68030  -m68040  -m68881
          -mbitfield  -mc68000  -mc68020  -mfpa  -mnobitfield
          -mrtd  -mshort  -msoft-float

          *VAX Options*
          -mg  -mgnu  -munix

          *SPARC Options*
          -mapp-regs  -mcypress  -mepilogue  -mflat  -mfpu  -mhard-float
          -mhard-quad-float  -mno-app-regs  -mno-flat  -mno-fpu
          -mno-epilogue  -mno-unaligned-doubles
          -msoft-float  -msoft-quad-float
          -msparclite  -msupersparc  -munaligned-doubles  -mv8

          SPARC V9 compilers support the following options
          in addition to the above:

          -mmedlow  -mmedany
          -mint32  -mint64  -mlong32  -mlong64
          -mno-stack-bias  -mstack-bias

          *Convex Options*
          -mc1  -mc2  -mc32  -mc34  -mc38
          -margcount  -mnoargcount
          -mlong32  -mlong64
          -mvolatile-cache  -mvolatile-nocache

          *AMD29K Options*
          -m29000  -m29050  -mbw  -mnbw  -mdw  -mndw
          -mlarge  -mnormal  -msmall
          -mkernel-registers  -mno-reuse-arg-regs
          -mno-stack-check  -mno-storem-bug
          -mreuse-arg-regs  -msoft-float  -mstack-check
          -mstorem-bug  -muser-registers

          *ARM Options*
          -mapcs -m2 -m3 -m6 -mbsd -mxopen -mno-symrename

          *M88K Options*
          -m88000  -m88100  -m88110  -mbig-pic
          -mcheck-zero-division  -mhandle-large-shift
          -midentify-revision  -mno-check-zero-division
          -mno-ocs-debug-info  -mno-ocs-frame-position
          -mno-optimize-arg-area  -mno-serialize-volatile
          -mno-underscores  -mocs-debug-info
          -mocs-frame-position  -moptimize-arg-area
          -mserialize-volatile  -mshort-data-NUM  -msvr3
          -msvr4  -mtrap-large-shift  -muse-div-instruction
          -mversion-03.00  -mwarn-passed-structs

          *RS/6000 and PowerPC Options*
          -mcpu=CPU  TYPE
          -mpower  -mno-power  -mpower2  -mno-power2
          -mpowerpc  -mno-powerpc
          -mpowerpc-gpopt  -mno-powerpc-gpopt
          -mpowerpc-gfxopt  -mno-powerpc-gfxopt
          -mnew-mnemonics  -mno-new-mnemonics
          -mfull-toc   -mminimal-toc  -mno-fop-in-toc  -mno-sum-in-toc
          -msoft-float  -mhard-float -mmultiple -mno-multiple
          -mstring -mno-string -mbit-align -mno-bit-align
          -mstrict-align -mno-strict-align -mrelocatable -mno-relocatable
          -mtoc -mno-toc -mtraceback -mno-traceback
          -mlittle -mlittle-endian -mbig -mbig-endian
          -mcall-aix -mcall-sysv -mprototype

          *RT Options*
          -mcall-lib-mul  -mfp-arg-in-fpregs  -mfp-arg-in-gregs
          -mfull-fp-blocks  -mhc-struct-return  -min-line-mul
          -mminimum-fp-blocks  -mnohc-struct-return

          *MIPS Options*
          -mabicalls  -mcpu=CPU  TYPE  -membedded-data
          -membedded-pic  -mfp32  -mfp64  -mgas  -mgp32  -mgp64
          -mgpopt  -mhalf-pic  -mhard-float  -mint64 -mips1
          -mips2 -mips3  -mlong64  -mlong-calls  -mmemcpy
          -mmips-as  -mmips-tfile  -mno-abicalls
          -mno-embedded-data  -mno-embedded-pic
          -mno-gpopt  -mno-long-calls
          -mno-memcpy  -mno-mips-tfile  -mno-rnames  -mno-stats
          -mrnames -msoft-float
          -m4650 -msingle-float -mmad
          -mstats  -EL  -EB  -G NUM  -nocpp

          *i386 Options*
          -m486  -m386 -mieee-fp  -mno-fancy-math-387
          -mno-fp-ret-in-387  -msoft-float  -msvr3-shlib
          -mno-wide-multiply -mrtd -malign-double
          -mreg-alloc=LIST -mregparm=NUM
          -malign-jumps=NUM -malign-loops=NUM
          -malign-functions=NUM

          *HPPA Options*
          -mdisable-fpregs  -mdisable-indexing  -mfast-indirect-calls
          -mgas  -mjump-in-delay -mlong-millicode-calls -mno-disable-fpregs
          -mno-disable-indexing -mno-fast-indirect-calls -mno-gas
          -mno-jump-in-delay -mno-millicode-long-calls
          -mno-portable-runtime -mno-soft-float -msoft-float
          -mpa-risc-1-0  -mpa-risc-1-1  -mportable-runtime -mschedule=LIST

          *Intel 960 Options*
          -mCPU TYPE  -masm-compat  -mclean-linkage
          -mcode-align  -mcomplex-addr  -mleaf-procedures
          -mic-compat  -mic2.0-compat  -mic3.0-compat
          -mintel-asm  -mno-clean-linkage  -mno-code-align
          -mno-complex-addr  -mno-leaf-procedures
          -mno-old-align  -mno-strict-align  -mno-tail-call
          -mnumerics  -mold-align  -msoft-float  -mstrict-align
          -mtail-call

          *DEC Alpha Options*
          -mfp-regs  -mno-fp-regs  -mno-soft-float
          -msoft-float

          *Clipper Options*
          -mc300 -mc400

          *H8/300 Options*
          -mrelax  -mh

          *System V Options*
          -Qy  -Qn  -YP,PATHS  -Ym,DIR

* Menu:

* Overall Options::        Controlling the kind of output:
                           an executable, object files, assembler files,
                           or preprocessed source.
* Pascal Dialect Options:: Controlling the variant of Pascal language compiled.
* Code Gen Options::       Specifying conventions for function calls, data
                           layout and register usage.
* Warning Options::        How picky should the compiler be?
* Debugging Options::      Symbol tables, measurements, and debugging dumps.
* Optimize Options::       How much optimization?
* Preprocessor Options::   Controlling header files and macro definitions.
                           Also, getting dependency information for Make.
* Assembler Options::      Passing options to the assembler.
* Link Options::           Specifying libraries and so on.
* Directory Options::      Where to find header files and libraries.
                           Where to find the compiler executable files.
* Target Options::         Running a cross-compiler, or an old version
                           of GNU Pascal.
* Submodel Options::       Specifying minor hardware or convention variations,
                           such as 68010 vs 68020.
* Environment Variables::  Env vars that affect GNU Pascal.


File: ^.!gcc.docs.pascal.gpc,  Node: Overall Options,  Next: Pascal Dialect Options,  Prev: Option Summary,  Up: Invoking GPC

Options Controlling the Kind of Output
======================================

   Compilation can involve up to four stages: preprocessing, compilation
proper, assembly and linking, always in that order.  The first three
stages apply to an individual source file, and end by producing an
object file; linking combines all the object files (those newly
compiled, and those specified as input) into an executable file.

   For any given input file, the file name suffix determines what kind
of compilation is done:

`FILE.p'
`FILE.pas'
     Pascal source code which must be preprocessed.

`FILE.i'
     Pascal source code which should not be preprocessed.

`FILE.h'
     Pascal header file (not to be compiled or linked).

`FILE.s'
     Assembler code.

`FILE.S'
     Assembler code which must be preprocessed.

`OTHER'
     An object file to be fed straight into linking.  Any file name
     with no recognized suffix is treated this way.

   You can specify the input language explicitly with the `-x' option:

`-x LANGUAGE'
     Specify explicitly the LANGUAGE for the following input files
     (rather than letting the compiler choose a default based on the
     file name suffix).  This option applies to all following input
     files until the next `-x' option.  Possible values for LANGUAGE
     are:
          pascal c  objective-c  c++
          c-header  cpp-output  c++-cpp-output
          assembler  assembler-with-cpp

`-x none'
     Turn off any specification of a language, so that subsequent files
     are handled according to their file name suffixes (as they are if
     `-x' has not been used at all).

   If you only want some of the stages of compilation, you can use `-x'
(or filename suffixes) to tell `gcc' where to start, and one of the
options `-c', `-S', or `-E' to say where `gpc' is to stop.  Note that
some combinations (for example, `-x cpp-output -E' instruct `gpc' to do
nothing at all.

`-c'
     Compile or assemble the source files, but do not link.  The linking
     stage simply is not done.  The ultimate output is in the form of an
     object file for each source file.

     By default, the object file name for a source file is made by
     replacing the suffix `.p', `.pas', `.i', `.s', etc., with `.o'.

     Unrecognized input files, not requiring compilation or assembly,
     are ignored.

`--automake'
     Check whether Modules/Units used by the main program must be
     recompiled and do the recompilation.  For example, if the program
     `mainprog.pas' uses the Modules `module1.pas' and `module2.pas',
     the modules are automatically compiled if necessary when you
     specify
            gpc --automake mainprog.pas

     Options to be passed to "child" compilations must be given
     explicitely as a "String" argument to -automake, for example:
            gpc -O --automake="-O" mainprog.pas

     (For an explanation of the -O option, see *Note Optimize
     Options::.)

     *WARNING:* The AutoMake mechanism is a new feature in version 2.7.2
     and may be unstable.

`-S'
     Stop after the stage of compilation proper; do not assemble.  The
     output is in the form of an assembler code file for each
     non-assembler input file specified.

     By default, the assembler file name for a source file is made by
     replacing the suffix `.p', `.pas', `.i', etc., with `.s'.

     Input files that don't require compilation are ignored.

`-E'
     Stop after the preprocessing stage; do not run the compiler
     proper.  The output is in the form of preprocessed source code,
     which is sent to the standard output.

     Input files which don't require preprocessing are ignored.

`-o FILE'
     Place output in file FILE.  This applies regardless to whatever
     sort of output is being produced, whether it be an executable file,
     an object file, an assembler file or preprocessed C code.

     Since only one output file can be specified, it does not make
     sense to use `-o' when compiling more than one input file, unless
     you are producing an executable file as output.

     If `-o' is not specified, the default is to put an executable file
     in `a.out', the object file for `SOURCE.SUFFIX' in `SOURCE.o', its
     assembler file in `SOURCE.s', and all preprocessed C source on
     standard output.

`-v'
     Print (on standard error output) the commands executed to run the
     stages of compilation.  Also print the version number of the
     compiler driver program and of the preprocessor and the compiler
     proper.

`-pipe'
     Use pipes rather than temporary files for communication between the
     various stages of compilation.  This fails to work on some systems
     where the assembler is unable to read from a pipe; but the GNU
     assembler has no trouble.


File: ^.!gcc.docs.pascal.gpc,  Node: Pascal Dialect Options,  Next: Code Gen Options,  Prev: Overall Options,  Up: Invoking GPC

Options Controlling Pascal Dialect
==================================

   In cases where the different Pascal dialects contradict, GNU Pascal
complies to the ISO standard by default.  However you can change this
behavior using command-line options or associated compiler switches.

`--nested-comments  (*$N+*)'
     Enable { nested comments (* like this one *) in your } Pascal
     source.  Without this option, comments may start with { and end
     with *).

     The compiler switch `$N' is equivalent to `--nested-comments' and
     allows local specifications.

     *A cross reference to compiler switches is in preparation.*

`--char-escapes  (*$E+*)'
     Enable C-style character escape sequences in strings.

`--c-numbers  (*$C+*)'
     Enable C-style octal and hexadecimal numbers: The decimal number
     255 is equal to the hexadecimal number `16#FF' (Extended Pascal
     notation) or `$FF' (Borland Pascal notation) or `0xFF' (C
     notation--works only with this switch active) or the octal number
     `0177' (C notation--ditto).

`--standard-pascal --extended-pascal --object-pascal --borland-pascal --pascal-sc'
     By default, GNU Pascal allows redefinition of keywords.  Each of
     this switches causes GNU Pascal to forbid the redefinition of
     keywords of the specified standard.

     Furthermore, `--borland-pascal' implies `--nested-comments' (see
     above), and `--pascal-sc' implies `--extended-syntax' (see below).

`--extended-syntax  (*$X+*)'
     Enables "dangerous" features of GNU Pascal such as
        * function return value ignore (works always, but gives warning
          without         -extended-syntax or $X+),

        * user-defined operators (Pascal-SC style),

        * *other extensions we are working on*.


File: ^.!gcc.docs.pascal.gpc,  Node: Code Gen Options,  Next: Warning Options,  Prev: Pascal Dialect Options,  Up: Invoking GPC

Options for Code Generation Conventions
=======================================

   These machine-independent options control the interface conventions
used in code generation.

   Most of them have both positive and negative forms; the negative form
of `-ffoo' would be `-fno-foo'.  In the table below, only one of the
forms is listed--the one which is not the default.  You can figure out
the other form by either removing `no-' or adding it.

`--short-circuit  (*$B-*)'
     Use short circuit evaluation of Boolean expressions.  By default,
     Boolean expressions are evaluated completely even if the result is
     kwown already.

`--lazy-io  (*$L+*)'
     Enable "lazy I/O", i.e. do a `put' as soon as you can and do `get'
     as late as you can.

`--setlimit:NUMBER'
     Define the maximum number of elements a set can hold to be NUMBER.

`--pcc-struct-return'
     Return "short" `Record' values in memory like longer ones, rather
     than in registers.  This convention is less efficient, but it has
     the advantage of allowing intercallability between GNU
     Pascal-compiled files and files compiled with other compilers.

     The precise convention for returning structures in memory depends
     on the target configuration macros.

     Short structures and unions are those whose size and alignment
     match that of some integer type.

`--reg-struct-return'
     Use the convention that `Record' values are returned in registers
     when possible.  This is more efficient for small structures than
     `--pcc-struct-return'.

     If you specify neither `--pcc-struct-return' nor its contrary
     `--reg-struct-return', GNU Pascal defaults to whichever convention
     is standard for the target.  If there is no standard convention,
     GNU Pascal defaults to `--pcc-struct-return', except on targets
     where GNU Pascal is the principal compiler.  In those cases, we
     can choose the standard, and we chose the more efficient register
     return alternative.

`--short-enums'
     Allocate to enumeral types only as many bytes as it needs for the
     declared range of possible values.

`--short-double'
     Use a smaller size for `Real'.

`--shared-data'
     Requests that the data and non-`const' variables of this
     compilation be shared data rather than private data.  The
     distinction makes sense only on certain operating systems, where
     shared data is shared between processes running the same program,
     while private data exists in one copy per process.

`--no-common'
     Allocate even uninitialized global variables in the bss section of
     the object file, rather than generating them as common blocks.
     This has the effect that if the same variable is declared (without
     `external') in two different compilations, you will get an error
     when you link them.  The only reason this might be useful is if
     you wish to verify that the program will work on other systems
     which always work this way.

`--no-ident'
     Ignore the `#ident' directive.

`--no-gnu-linker'
     Do not output global initializations (such as C++ constructors and
     destructors) in the form used by the GNU linker (on systems where
     the GNU linker is the standard method of handling them).  Use this
     option when you want to use a non-GNU linker, which also requires
     using the `collect2' program to make sure the system linker
     includes constructors and destructors.  (`collect2' is included in
     the GNU Pascal distribution.)  For systems which *must* use
     `collect2', the compiler driver `gpc' is configured to do this
     automatically.

`--inhibit-size-directive'
     Don't output a `.size' assembler directive, or anything else that
     would cause trouble if the function is split in the middle, and the
     two halves are placed at locations far apart in memory.  This
     option is used when compiling `crtstuff.c'; you should not need to
     use it for anything else.

`--verbose-asm'
     Put extra commentary information in the generated assembly code to
     make it more readable.  This option is generally only of use to
     those who actually need to read the generated assembly code
     (perhaps while debugging the compiler itself).

`--volatile'
     Consider all memory references through pointers to be volatile.

`--volatile-global'
     Consider all memory references to external and global data items to
     be volatile.

`--pic'
     Generate position-independent code (PIC) suitable for use in a
     shared library, if supported for the target machine.  Such code
     accesses all constant addresses through a global offset table
     (GOT).  If the GOT size for the linked executable exceeds a
     machine-specific maximum size, you get an error message from the
     linker indicating that `--pic' does not work; in that case,
     recompile with `--PIC' instead.  (These maximums are 16k on the
     m88k, 8k on the Sparc, and 32k on the m68k and RS/6000.  The 386
     has no such limit.)

     Position-independent code requires special support, and therefore
     works only on certain machines.  For the 386, GNU Pascal supports
     PIC for System V but not for the Sun 386i.  Code generated for the
     IBM RS/6000 is always position-independent.

     The GNU assembler does not fully support PIC.  Currently, you must
     use some other assembler in order for PIC to work.  We would
     welcome volunteers to upgrade GAS to handle this; the first part
     of the job is to figure out what the assembler must do differently.

`--PIC'
     If supported for the target machine, emit position-independent
     code, suitable for dynamic linking and avoiding any limit on the
     size of the global offset table.  This option makes a difference
     on the m68k, m88k and the Sparc.

     Position-independent code requires special support, and therefore
     works only on certain machines.

`--fixed-REG'
     Treat the register named REG as a fixed register; generated code
     should never refer to it (except perhaps as a stack pointer, frame
     pointer or in some other fixed role).

     REG must be the name of a register.  The register names accepted
     are machine-specific and are defined in the `REGISTER_NAMES' macro
     in the machine description macro file.

     This flag does not have a negative form, because it specifies a
     three-way choice.

`--call-used-REG'
     Treat the register named REG as an allocatable register that is
     clobbered by function calls.  It may be allocated for temporaries
     or variables that do not live across a call.  Functions compiled
     this way will not save and restore the register REG.

     Use of this flag for a register that has a fixed pervasive role in
     the machine's execution model, such as the stack pointer or frame
     pointer, will produce disastrous results.

     This flag does not have a negative form, because it specifies a
     three-way choice.

`--call-saved-REG'
     Treat the register named REG as an allocatable register saved by
     functions.  It may be allocated even for temporaries or variables
     that live across a call.  Functions compiled this way will save
     and restore the register REG if they use it.

     Use of this flag for a register that has a fixed pervasive role in
     the machine's execution model, such as the stack pointer or frame
     pointer, will produce disastrous results.

     A different sort of disaster will result from the use of this flag
     for a register in which function values may be returned.

     This flag does not have a negative form, because it specifies a
     three-way choice.

`--pack-struct'
     Pack all structure members together without holes.  Usually you
     would not want to use this option, since it makes the code
     suboptimal, and the offsets of structure members won't agree with
     system libraries.


File: ^.!gcc.docs.pascal.gpc,  Node: Warning Options,  Next: Debugging Options,  Prev: Code Gen Options,  Up: Invoking GPC

Options to Request or Suppress Warnings
=======================================

   Warnings are diagnostic messages that report constructions which are
not inherently erroneous but which are risky or suggest there may have
been an error.

   You can request many specific warnings with options beginning `-W',
for example `-Wimplicit' to request warnings on implicit declarations.
Each of these specific warning options also has a negative form
beginning `-Wno-' to turn off warnings; for example, `-Wno-implicit'.
This manual lists only one of the two forms, whichever is not the
default.

   These options control the amount and kinds of warnings produced by
GNU Pascal:

   *GPC note: theses are all in toplev.c, but not all of them apply.*

`-fsyntax-only'
     Check the code for syntax errors, but don't do anything beyond
     that.

`-pedantic'
     Issue all the warnings demanded by strict ANSI standard Pascal;
     reject all programs that use forbidden extensions.

     Valid ANSI standard Pascal programs should compile properly with
     or without this option (though a rare few will require `-ansi').
     However, without this option, certain GNU extensions and
     traditional Pascal features are supported as well.  With this
     option, they are rejected.

     `-pedantic' does not cause warning messages for use of the
     alternate keywords whose names begin and end with `__'.  Pedantic
     warnings are also disabled in the expression that follows
     `__extension__'.  However, only system header files should use
     these escape routes; application programs should avoid them.

     This option is not intended to be useful; it exists only to satisfy
     pedants who would otherwise claim that GNU CC fails to support the
     ANSI standard.

     Some users try to use `-pedantic' to check programs for strict ANSI
     C conformance.  They soon find that it does not do quite what they
     want: it finds some non-ANSI practices, but not all--only those
     for which ANSI C *requires* a diagnostic.

     A feature to report any failure to conform to ANSI C might be
     useful in some instances, but would require considerable
     additional work and would be quite different from `-pedantic'.  We
     recommend, rather, that users take advantage of the extensions of
     GNU C and disregard the limitations of other compilers.  Aside
     from certain supercomputers and obsolete small machines, there is
     less and less reason ever to use any other C compiler other than
     for bootstrapping GNU CC.

`-pedantic-errors'
     Like `-pedantic', except that errors are produced rather than
     warnings.

`-w'
     Inhibit all warning messages.

`-Wno-import'
     Inhibit warning messages about the use of `#import'.

`-Wchar-subscripts'
     Warn if an array subscript has type `char'.  This is a common cause
     of error, as programmers often forget that this type is signed on
     some machines.

`-Wcomment'
     Warn whenever a comment-start sequence `/*' appears in a comment.

`-Wformat'
     Check calls to `printf' and `scanf', etc., to make sure that the
     arguments supplied have types appropriate to the format string
     specified.

`-Wimplicit'
     Warn whenever a function or parameter is implicitly declared.

`-Wparentheses'
     Warn if parentheses are omitted in certain contexts, such as when
     there is an assignment in a context where a truth value is
     expected, or when operators are nested whose precedence people
     often get confused about.

`-Wreturn-type'
     Warn whenever a function is defined with a return-type that
     defaults to `int'.  Also warn about any `return' statement with no
     return-value in a function whose return-type is not `void'.

`-Wswitch'
     Warn whenever a `switch' statement has an index of enumeral type
     and lacks a `case' for one or more of the named codes of that
     enumeration.  (The presence of a `default' label prevents this
     warning.)  `case' labels outside the enumeration range also
     provoke warnings when this option is used.

`-Wtrigraphs'
     Warn if any trigraphs are encountered (assuming they are enabled).

`-Wunused'
     Warn whenever a variable is unused aside from its declaration,
     whenever a function is declared static but never defined, whenever
     a label is declared but not used, and whenever a statement
     computes a result that is explicitly not used.

     To suppress this warning for an expression, simply cast it to
     void.  For unused variables and parameters, use the `unused'
     attribute.

`-Wuninitialized'
     An automatic variable is used without first being initialized.

     These warnings are possible only in optimizing compilation,
     because they require data flow information that is computed only
     when optimizing.  If you don't specify `-O', you simply won't get
     these warnings.

     These warnings occur only for variables that are candidates for
     register allocation.  Therefore, they do not occur for a variable
     that is declared `volatile', or whose address is taken, or whose
     size is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
     structures, unions or arrays, even when they are in registers.

     Note that there may be no warning about a variable that is used
     only to compute a value that itself is never used, because such
     computations may be deleted by data flow analysis before the
     warnings are printed.

     These warnings are made optional because GNU CC is not smart
     enough to see all the reasons why the code might be correct
     despite appearing to have an error.  Here is one example of how
     this can happen:

          {
            int x;
            switch (y)
              {
              case 1: x = 1;
                break;
              case 2: x = 4;
                break;
              case 3: x = 5;
              }
            foo (x);
          }

     If the value of `y' is always 1, 2 or 3, then `x' is always
     initialized, but GNU CC doesn't know this.  Here is another common
     case:

          {
            int save_y;
            if (change_y) save_y = y, y = new_y;
            ...
            if (change_y) y = save_y;
          }

     This has no bug because `save_y' is used only if it is set.

     Some spurious warnings can be avoided if you declare all the
     functions you use that never return as `noreturn'.

`-Wall'
     All of the above `-W' options combined.  These are all the options
     which pertain to usage that we recommend avoiding and that we
     believe is easy to avoid, even in conjunction with macros.

   The remaining `-W...' options are not implied by `-Wall' because
they warn about constructions that we consider reasonable to use, on
occasion, in clean programs.

`-W'
     Print extra warning messages for these events:

        * A nonvolatile automatic variable might be changed by a call to
          `longjmp'.  These warnings as well are possible only in
          optimizing compilation.

          The compiler sees only the calls to `setjmp'.  It cannot know
          where `longjmp' will be called; in fact, a signal handler
          could call it at any point in the code.  As a result, you may
          get a warning even when there is in fact no problem because
          `longjmp' cannot in fact be called at the place which would
          cause a problem.

        * A function can return either with or without a value.
          (Falling off the end of the function body is considered
          returning without a value.)  For example, this function would
          evoke such a warning:

               foo (a)
               {
                 if (a > 0)
                   return a;
               }

        * An expression-statement or the left-hand side of a comma
          expression contains no side effects.  To suppress the
          warning, cast the unused expression to void.  For example, an
          expression such as `x[i,j]' will cause a warning, but
          `x[(void)i,j]' will not.

        * An unsigned value is compared against zero with `<' or `<='.

        * A comparison like `x<=y<=z' appears; this is equivalent to
          `(x<=y ? 1 : 0) <= z', which is a different interpretation
          from that of ordinary mathematical notation.

        * Storage-class specifiers like `static' are not the first
          things in a declaration.  According to the C Standard, this
          usage is obsolescent.

        * If `-Wall' or `-Wunused' is also specified, warn about unused
          arguments.

        * An aggregate has a partly bracketed initializer.  For
          example, the following code would evoke such a warning,
          because braces are missing around the initializer for `x.h':

               struct s { int f, g; };
               struct t { struct s h; int i; };
               struct t x = { 1, 2, 3 };

`-Wtraditional'
     Warn about certain constructs that behave differently in
     traditional and ANSI C.

        * Macro arguments occurring within string constants in the
          macro body.  These would substitute the argument in
          traditional C, but are part of the constant in ANSI C.

        * A function declared external in one block and then used after
          the end of the block.

        * A `switch' statement has an operand of type `long'.

`-Wshadow'
     Warn whenever a local variable shadows another local variable.

`-Wid-clash-LEN'
     Warn whenever two distinct identifiers match in the first LEN
     characters.  This may help you prepare a program that will compile
     with certain obsolete, brain-damaged compilers.

`-Wlarger-than-LEN'
     Warn whenever an object of larger than LEN bytes is defined.

`-Wpointer-arith'
     Warn about anything that depends on the "size of" a function type
     or of `void'.  GNU C assigns these types a size of 1, for
     convenience in calculations with `void *' pointers and pointers to
     functions.

`-Wbad-function-cast'
     Warn whenever a function call is cast to a non-matching type.  For
     example, warn if `int malloc()' is cast to `anything *'.

`-Wcast-qual'
     Warn whenever a pointer is cast so as to remove a type qualifier
     from the target type.  For example, warn if a `const char *' is
     cast to an ordinary `char *'.

`-Wcast-align'
     Warn whenever a pointer is cast such that the required alignment
     of the target is increased.  For example, warn if a `char *' is
     cast to an `int *' on machines where integers can only be accessed
     at two- or four-byte boundaries.

`-Wwrite-strings'
     Give string constants the type `const char[LENGTH]' so that
     copying the address of one into a non-`const' `char *' pointer
     will get a warning.  These warnings will help you find at compile
     time code that can try to write into a string constant, but only
     if you have been very careful about using `const' in declarations
     and prototypes.  Otherwise, it will just be a nuisance; this is
     why we did not make `-Wall' request these warnings.

`-Wconversion'
     Warn if a prototype causes a type conversion that is different
     from what would happen to the same argument in the absence of a
     prototype.  This includes conversions of fixed point to floating
     and vice versa, and conversions changing the width or signedness
     of a fixed point argument except when the same as the default
     promotion.

     Also, warn if a negative integer constant expression is implicitly
     converted to an unsigned type.  For example, warn about the
     assignment `x = -1' if `x' is unsigned.  But do not warn about
     explicit casts like `(unsigned) -1'.

`-Waggregate-return'
     Warn if any functions that return structures or unions are defined
     or called.  (In languages where you can return an array, this also
     elicits a warning.)

`-Wstrict-prototypes'
     Warn if a function is declared or defined without specifying the
     argument types.  (An old-style function definition is permitted
     without a warning if preceded by a declaration which specifies the
     argument types.)

`-Wmissing-prototypes'
     Warn if a global function is defined without a previous prototype
     declaration.  This warning is issued even if the definition itself
     provides a prototype.  The aim is to detect global functions that
     fail to be declared in header files.

`-Wmissing-declarations'
     Warn if a global function is defined without a previous
     declaration.  Do so even if the definition itself provides a
     prototype.  Use this option to detect global functions that are
     not declared in header files.

`-Wredundant-decls'
     Warn if anything is declared more than once in the same scope,
     even in cases where multiple declaration is valid and changes
     nothing.

`-Wnested-externs'
     Warn if an `extern' declaration is encountered within an function.

`-Winline'
     Warn if a function can not be inlined, and either it was declared
     as inline, or else the `-finline-functions' option was given.

`-Woverloaded-virtual'
     Warn when a derived class function declaration may be an error in
     defining a virtual function (C++ only).  In a derived class, the
     definitions of virtual functions must match the type signature of a
     virtual function declared in the base class.  With this option, the
     compiler warns when you define a function with the same name as a
     virtual function, but with a type signature that does not match any
     declarations from the base class.

`-Wsynth (C++ only)'
     Warn when g++'s synthesis behavior does not match that of cfront.
     For instance:

          struct A {
            operator int ();
            A& operator = (int);
          };

          main ()
          {
            A a,b;
            a = b;
          }

     In this example, g++ will synthesize a default `A& operator =
     (const A&);', while cfront will use the user-defined `operator ='.

`-Werror'
     Make all warnings into errors.


File: ^.!gcc.docs.pascal.gpc,  Node: Debugging Options,  Next: Optimize Options,  Prev: Warning Options,  Up: Invoking GPC

Options for Debugging Your Program or GNU Pascal
================================================

   GNU Pascal has various special options that are used for debugging
either your program or GPC:

`-g'
     Produce debugging information in the operating system's native
     format (stabs, COFF, XCOFF, or DWARF).  GDB can work with this
     debugging information.

     On most systems that use stabs format, `-g' enables use of extra
     debugging information that only GDB can use; this extra information
     makes debugging work better in GDB but will probably make other
     debuggers crash or refuse to read the program.  If you want to
     control for certain whether to generate the extra information, use
     `-gstabs+', `-gstabs', `-gxcoff+', `-gxcoff', `-gdwarf+', or
     `-gdwarf' (see below).

     Unlike most other C compilers, GNU Pascal allows you to use `-g'
     with `-O'.  The shortcuts taken by optimized code may occasionally
     produce surprising results: some variables you declared may not
     exist at all; flow of control may briefly move where you did not
     expect it; some statements may not be executed because they
     compute constant results or their values were already at hand;
     some statements may execute in different places because they were
     moved out of loops.

     Nevertheless it proves possible to debug optimized output.  This
     makes it reasonable to use the optimizer for programs that might
     have bugs.

     The following options are useful when GNU Pascal is generated with
     the capability for more than one debugging format.

`-ggdb'
     Produce debugging information in the native format (if that is
     supported), including GDB extensions if at all possible.

`-gstabs'
     Produce debugging information in stabs format (if that is
     supported), without GDB extensions.  This is the format used by
     DBX on most BSD systems.  On MIPS, Alpha and System V Release 4
     systems this option produces stabs debugging output which is not
     understood by DBX or SDB.  On System V Release 4 systems this
     option requires the GNU assembler.

`-gstabs+'
     Produce debugging information in stabs format (if that is
     supported), using GNU extensions understood only by the GNU
     debugger (GDB).  The use of these extensions is likely to make
     other debuggers crash or refuse to read the program.

`-gcoff'
     Produce debugging information in COFF format (if that is
     supported).  This is the format used by SDB on most System V
     systems prior to System V Release 4.

`-gxcoff'
     Produce debugging information in XCOFF format (if that is
     supported).  This is the format used by the DBX debugger on IBM
     RS/6000 systems.

`-gxcoff+'
     Produce debugging information in XCOFF format (if that is
     supported), using GNU extensions understood only by the GNU
     debugger (GDB).  The use of these extensions is likely to make
     other debuggers crash or refuse to read the program, and may cause
     assemblers other than the GNU assembler (GAS) to fail with an
     error.

`-gdwarf'
     Produce debugging information in DWARF format (if that is
     supported).  This is the format used by SDB on most System V
     Release 4 systems.

`-gdwarf+'
     Produce debugging information in DWARF format (if that is
     supported), using GNU extensions understood only by the GNU
     debugger (GDB).  The use of these extensions is likely to make
     other debuggers crash or refuse to read the program.

`-gLEVEL'
`-ggdbLEVEL'
`-gstabsLEVEL'
`-gcoffLEVEL'
`-gxcoffLEVEL'
`-gdwarfLEVEL'
     Request debugging information and also use LEVEL to specify how
     much information.  The default level is 2.

     Level 1 produces minimal information, enough for making backtraces
     in parts of the program that you don't plan to debug.  This
     includes descriptions of functions and external variables, but no
     information about local variables and no line numbers.

     Level 3 includes extra information, such as all the macro
     definitions present in the program.  Some debuggers support macro
     expansion when you use `-g3'.

`-p'
     Generate extra code to write profile information suitable for the
     analysis program `prof'.  You must use this option when compiling
     the source files you want data about, and you must also use it when
     linking.

`-pg'
     Generate extra code to write profile information suitable for the
     analysis program `gprof'.  You must use this option when compiling
     the source files you want data about, and you must also use it when
     linking.

`-a'
     Generate extra code to write profile information for basic blocks,
     which will record the number of times each basic block is
     executed, the basic block start address, and the function name
     containing the basic block.  If `-g' is used, the line number and
     filename of the start of the basic block will also be recorded.
     If not overridden by the machine description, the default action is
     to append to the text file `bb.out'.

     This data could be analyzed by a program like `tcov'.  Note,
     however, that the format of the data is not what `tcov' expects.
     Eventually GNU `gprof' should be extended to process this data.

`-dLETTERS'
     Says to make debugging dumps during compilation at times specified
     by LETTERS.  This is used for debugging the compiler.  The file
     names for most of the dumps are made by appending a word to the
     source file name (e.g.  `foo.c.rtl' or `foo.c.jump').  Here are the
     possible letters for use in LETTERS, and their meanings:

    `M'
          Dump all macro definitions, at the end of preprocessing, and
          write no output.

    `N'
          Dump all macro names, at the end of preprocessing.

    `D'
          Dump all macro definitions, at the end of preprocessing, in
          addition to normal output.

    `y'
          Dump debugging information during parsing, to standard error.

    `r'
          Dump after RTL generation, to `FILE.rtl'.

    `x'
          Just generate RTL for a function instead of compiling it.
          Usually used with `r'.

    `j'
          Dump after first jump optimization, to `FILE.jump'.

    `s'
          Dump after CSE (including the jump optimization that sometimes
          follows CSE), to `FILE.cse'.

    `L'
          Dump after loop optimization, to `FILE.loop'.

    `t'
          Dump after the second CSE pass (including the jump
          optimization that sometimes follows CSE), to `FILE.cse2'.

    `f'
          Dump after flow analysis, to `FILE.flow'.

    `c'
          Dump after instruction combination, to the file
          `FILE.combine'.

    `S'
          Dump after the first instruction scheduling pass, to
          `FILE.sched'.

    `l'
          Dump after local register allocation, to `FILE.lreg'.

    `g'
          Dump after global register allocation, to `FILE.greg'.

    `R'
          Dump after the second instruction scheduling pass, to
          `FILE.sched2'.

    `J'
          Dump after last jump optimization, to `FILE.jump2'.

    `d'
          Dump after delayed branch scheduling, to `FILE.dbr'.

    `k'
          Dump after conversion from registers to stack, to
          `FILE.stack'.

    `a'
          Produce all the dumps listed above.

    `m'
          Print statistics on memory usage, at the end of the run, to
          standard error.

    `p'
          Annotate the assembler output with a comment indicating which
          pattern and alternative was used.

`-fpretend-float'
     When running a cross-compiler, pretend that the target machine
     uses the same floating point format as the host machine.  This
     causes incorrect output of the actual floating constants, but the
     actual instruction sequence will probably be the same as GNU
     Pascal would make when running on the target machine.

`-save-temps'
     Store the usual "temporary" intermediate files permanently; place
     them in the current directory and name them based on the source
     file.  Thus, compiling `foo.c' with `-c -save-temps' would produce
     files `foo.i' and `foo.s', as well as `foo.o'.

`-print-file-name=LIBRARY'
     Print the full absolute name of the library file LIBRARY that
     would be used when linking--and don't do anything else.  With this
     option, GNU Pascal does not compile or link anything; it just
     prints the file name.

`-print-prog-name=PROGRAM'
     Like `-print-file-name', but searches for a program such as `cpp'.

`-print-libgcc-file-name'
     Same as `-print-file-name=libgcc.a'.

     This is useful when you use `-nostdlib' or `-nodefaultlibs' but
     you do want to link with `libgcc.a'.  You can do

          gcc -nostdlib FILES... `gcc -print-libgcc-file-name`

`-print-search-dirs'
     Print the name of the configured installation directory and a list
     of program and library directories gcc will search--and don't do
     anything else.

     This is useful when gcc prints the error message `installation
     problem, cannot exec cpp: No such file or directory'.  To resolve
     this you either need to put `cpp' and the other compiler
     components where gcc expects to find them, or you can set the
     environment variable `GPC_EXEC_PREFIX' to the directory where you
     installed them.  Don't forget the trailing '/'.  *Note Environment
     Variables::.


File: ^.!gcc.docs.pascal.gpc,  Node: Optimize Options,  Next: Preprocessor Options,  Prev: Debugging Options,  Up: Invoking GPC

Options That Control Optimization
=================================

   These options control various sorts of optimizations:

`-O'
`-O1'
     Optimize.  Optimizing compilation takes somewhat more time, and a
     lot more memory for a large function.

     Without `-O', the compiler's goal is to reduce the cost of
     compilation and to make debugging produce the expected results.
     Statements are independent: if you stop the program with a
     breakpoint between statements, you can then assign a new value to
     any variable or change the program counter to any other statement
     in the function and get exactly the results you would expect from
     the source code.

     With `-O', the compiler tries to reduce code size and execution
     time.

     When you specify `-O', the compiler turns on `-fthread-jumps' and
     `-fdefer-pop' on all machines.  The compiler turns on
     `-fdelayed-branch' on machines that have delay slots, and
     `-fomit-frame-pointer' on machines that can support debugging even
     without a frame pointer.  On some machines the compiler also turns
     on other flags.

`-O2'
     Optimize even more.  GNU Pascal performs nearly all supported
     optimizations that do not involve a space-speed tradeoff.  The
     compiler does not perform loop unrolling or function inlining when
     you specify `-O2'.  As compared to `-O', this option increases
     both compilation time and the performance of the generated code.

     `-O2' turns on all optional optimizations except for loop unrolling
     and function inlining.  It also turns on the `-fforce-mem' option
     on all machines and frame pointer elimination on machines where
     doing so does not interfere with debugging.

`-O3'
     Optimize yet more.  `-O3' turns on all optimizations specified by
     `-O2' and also turns on the `inline-functions' option.

`-O0'
     Do not optimize.

     If you use multiple `-O' options, with or without level numbers,
     the last such option is the one that is effective.

   Options of the form `-fFLAG' specify machine-independent flags.
Most flags have both positive and negative forms; the negative form of
`-ffoo' would be `-fno-foo'.  In the table below, only one of the forms
is listed--the one which is not the default.  You can figure out the
other form by either removing `no-' or adding it.

`-ffloat-store'
     Do not store floating point variables in registers, and inhibit
     other options that might change whether a floating point value is
     taken from a register or memory.

     This option prevents undesirable excess precision on machines such
     as the 68000 where the floating registers (of the 68881) keep more
     precision than a `double' is supposed to have.  For most programs,
     the excess precision does only good, but a few programs rely on the
     precise definition of IEEE floating point.  Use `-ffloat-store' for
     such programs.

`-fno-default-inline'
     Do not make member functions inline by default merely because they
     are defined inside the class scope (C++ only).  Otherwise, when
     you specify `-O', member functions defined inside class scope are
     compiled inline by default; i.e., you don't need to add `inline'
     in front of the member function name.

`-fno-defer-pop'
     Always pop the arguments to each function call as soon as that
     function returns.  For machines which must pop arguments after a
     function call, the compiler normally lets arguments accumulate on
     the stack for several function calls and pops them all at once.

`-fforce-mem'
     Force memory operands to be copied into registers before doing
     arithmetic on them.  This produces better code by making all memory
     references potential common subexpressions.  When they are not
     common subexpressions, instruction combination should eliminate
     the separate register-load.  The `-O2' option turns on this option.

`-fforce-addr'
     Force memory address constants to be copied into registers before
     doing arithmetic on them.  This may produce better code just as
     `-fforce-mem' may.

`-fomit-frame-pointer'
     Don't keep the frame pointer in a register for functions that
     don't need one.  This avoids the instructions to save, set up and
     restore frame pointers; it also makes an extra register available
     in many functions.  *It also makes debugging impossible on some
     machines.*

     On some machines, such as the Vax, this flag has no effect, because
     the standard calling sequence automatically handles the frame
     pointer and nothing is saved by pretending it doesn't exist.  The
     machine-description macro `FRAME_POINTER_REQUIRED' controls
     whether a target machine supports this flag.  *Note Register
     Usage: (gcc.info)Registers.

`-fno-inline'
     Don't pay attention to the `inline' keyword.  Normally this option
     is used to keep the compiler from expanding any functions inline.
     Note that if you are not optimizing, no functions can be expanded
     inline.

`-finline-functions'
     Integrate all simple functions into their callers.  The compiler
     heuristically decides which functions are simple enough to be worth
     integrating in this way.

     If all calls to a given function are integrated, and the function
     is declared `static', then the function is normally not output as
     assembler code in its own right.

`-fkeep-inline-functions'
     Even if all calls to a given function are integrated, and the
     function is declared `static', nevertheless output a separate
     run-time callable version of the function.

`-fno-function-cse'
     Do not put function addresses in registers; make each instruction
     that calls a constant function contain the function's address
     explicitly.

     This option results in less efficient code, but some strange hacks
     that alter the assembler output may be confused by the
     optimizations performed when this option is not used.

`-ffast-math'
     This option allows GPC to violate some ANSI or IEEE rules and/or
     specifications in the interest of optimizing code for speed.  For
     example, it allows the compiler to assume arguments to the `sqrt'
     function are non-negative numbers and that no floating-point values
     are NaNs.

     This option should never be turned on by any `-O' option since it
     can result in incorrect output for programs which depend on an
     exact implementation of IEEE or ANSI rules/specifications for math
     functions.

   The following options control specific optimizations.  The `-O2'
option turns on all of these optimizations except `-funroll-loops' and
`-funroll-all-loops'.  On most machines, the `-O' option turns on the
`-fthread-jumps' and `-fdelayed-branch' options, but specific machines
may handle it differently.

   You can use the following flags in the rare cases when "fine-tuning"
of optimizations to be performed is desired.

`-fstrength-reduce'
     Perform the optimizations of loop strength reduction and
     elimination of iteration variables.

`-fthread-jumps'
     Perform optimizations where we check to see if a jump branches to a
     location where another comparison subsumed by the first is found.
     If so, the first branch is redirected to either the destination of
     the second branch or a point immediately following it, depending
     on whether the condition is known to be true or false.

`-fcse-follow-jumps'
     In common subexpression elimination, scan through jump instructions
     when the target of the jump is not reached by any other path.  For
     example, when CSE encounters an `if' statement with an `else'
     clause, CSE will follow the jump when the condition tested is
     false.

`-fcse-skip-blocks'
     This is similar to `-fcse-follow-jumps', but causes CSE to follow
     jumps which conditionally skip over blocks.  When CSE encounters a
     simple `if' statement with no else clause, `-fcse-skip-blocks'
     causes CSE to follow the jump around the body of the `if'.

`-frerun-cse-after-loop'
     Re-run common subexpression elimination after loop optimizations
     has been performed.

`-fexpensive-optimizations'
     Perform a number of minor optimizations that are relatively
     expensive.

`-fdelayed-branch'
     If supported for the target machine, attempt to reorder
     instructions to exploit instruction slots available after delayed
     branch instructions.

`-fschedule-insns'
     If supported for the target machine, attempt to reorder
     instructions to eliminate execution stalls due to required data
     being unavailable.  This helps machines that have slow floating
     point or memory load instructions by allowing other instructions
     to be issued until the result of the load or floating point
     instruction is required.

`-fschedule-insns2'
     Similar to `-fschedule-insns', but requests an additional pass of
     instruction scheduling after register allocation has been done.
     This is especially useful on machines with a relatively small
     number of registers and where memory load instructions take more
     than one cycle.

`-fcaller-saves'
     Enable values to be allocated in registers that will be clobbered
     by function calls, by emitting extra instructions to save and
     restore the registers around such calls.  Such allocation is done
     only when it seems to result in better code than would otherwise
     be produced.

     This option is enabled by default on certain machines, usually
     those which have no call-preserved registers to use instead.

`-funroll-loops'
     Perform the optimization of loop unrolling.  This is only done for
     loops whose number of iterations can be determined at compile time
     or run time.  `-funroll-loop' implies both `-fstrength-reduce' and
     `-frerun-cse-after-loop'.

`-funroll-all-loops'
     Perform the optimization of loop unrolling.  This is done for all
     loops and usually makes programs run more slowly.
     `-funroll-all-loops' implies `-fstrength-reduce' as well as
     `-frerun-cse-after-loop'.

`-fno-peephole'
     Disable any machine-specific peephole optimizations.


File: ^.!gcc.docs.pascal.gpc,  Node: Preprocessor Options,  Next: Assembler Options,  Prev: Optimize Options,  Up: Invoking GPC

Options Controlling the Preprocessor
====================================

   *Does the Pascal Preprocessor bring new options?*

   These options control the Pascal preprocessor, which is run on each
Pascal source file before actual compilation.

   If you use the `-E' option, nothing is done except preprocessing.
Some of these options make sense only together with `-E' because they
cause the preprocessor output to be unsuitable for actual compilation.

`-include FILE'
     Process FILE as input before processing the regular input file.
     In effect, the contents of FILE are compiled first.  Any `-D' and
     `-U' options on the command line are always processed before
     `-include FILE', regardless of the order in which they are
     written.  All the `-include' and `-imacros' options are processed
     in the order in which they are written.

`-imacros FILE'
     Process FILE as input, discarding the resulting output, before
     processing the regular input file.  Because the output generated
     from FILE is discarded, the only effect of `-imacros FILE' is to
     make the macros defined in FILE available for use in the main
     input.

     Any `-D' and `-U' options on the command line are always processed
     before `-imacros FILE', regardless of the order in which they are
     written.  All the `-include' and `-imacros' options are processed
     in the order in which they are written.

`-idirafter DIR'
     Add the directory DIR to the second include path.  The directories
     on the second include path are searched when a header file is not
     found in any of the directories in the main include path (the one
     that `-I' adds to).

`-iprefix PREFIX'
     Specify PREFIX as the prefix for subsequent `-iwithprefix' options.

`-iwithprefix DIR'
     Add a directory to the second include path.  The directory's name
     is made by concatenating PREFIX and DIR, where PREFIX was
     specified previously with `-iprefix'.  If you have not specified a
     prefix yet, the directory containing the installed passes of the
     compiler is used as the default.

`-iwithprefixbefore DIR'
     Add a directory to the main include path.  The directory's name is
     made by concatenating PREFIX and DIR, as in the case of
     `-iwithprefix'.

`-isystem DIR'
     Add a directory to the beginning of the second include path,
     marking it as a system directory, so that it gets the same special
     treatment as is applied to the standard system directories.

`-nostdinc'
     Do not search the standard system directories for header files.
     Only the directories you have specified with `-I' options (and the
     current directory, if appropriate) are searched.  *Note Directory
     Options::, for information on `-I'.

     By using both `-nostdinc' and `-I-', you can limit the include-file
     search path to only those directories you specify explicitly.

`-undef'
     Do not predefine any nonstandard macros.  (Including architecture
     flags).

`-E'
     Run only the Pascal preprocessor.  Preprocess all the Pascal
     source files specified and output the results to standard output
     or to the specified output file.

`-C'
     Tell the preprocessor not to discard comments.  Used with the `-E'
     option.

`-P'
     Tell the preprocessor not to generate `#line' directives.  Used
     with the `-E' option.

`-M'
     Tell the preprocessor to output a rule suitable for `make'
     describing the dependencies of each object file.  For each source
     file, the preprocessor outputs one `make'-rule whose target is the
     object file name for that source file and whose dependencies are
     all the `$include' header files it uses.  This rule may be a
     single line or may be continued with `\'-newline if it is long.
     The list of rules is printed on standard output instead of the
     preprocessed Pascal program.

     `-M' implies `-E'.

     Another way to specify output of a `make' rule is by setting the
     environment variable `DEPENDENCIES_OUTPUT' (*note Environment
     Variables::.).

`-MM'
     Like `-M' but the output mentions only the user header files
     included with `#include "FILE"'.  System header files included
     with `#include <FILE>' are omitted.

`-MD'
     Like `-M' but the dependency information is written to a file made
     by replacing ".c" with ".d" at the end of the input file names.
     This is in addition to compiling the file as specified--`-MD' does
     not inhibit ordinary compilation the way `-M' does.

     In Mach, you can use the utility `md' to merge multiple dependency
     files into a single dependency file suitable for using with the
     `make' command.

`-MMD'
     Like `-MD' except mention only user header files, not system
     header files.

`-MG'
     Treat missing header files as generated files and assume they live
     in the same directory as the source file.  If you specify `-MG',
     you must also specify either `-M' or `-MM'.  `-MG' is not
     supported with `-MD' or `-MMD'.

`-H'
     Print the name of each header file used, in addition to other
     normal activities.

`-AQUESTION(ANSWER)'
     Assert the answer ANSWER for QUESTION, in case it is tested with a
     preprocessing conditional such as `#if #QUESTION(ANSWER)'.  `-A-'
     disables the standard assertions that normally describe the target
     machine.

`-DMACRO'
     Define macro MACRO with the string `1' as its definition.

`-DMACRO=DEFN'
     Define macro MACRO as DEFN.  All instances of `-D' on the command
     line are processed before any `-U' options.

`-UMACRO'
     Undefine macro MACRO.  `-U' options are evaluated after all `-D'
     options, but before any `-include' and `-imacros' options.

`-dM'
     Tell the preprocessor to output only a list of the macro
     definitions that are in effect at the end of preprocessing.  Used
     with the `-E' option.

`-dD'
     Tell the preprocessing to pass all macro definitions into the
     output, in their proper sequence in the rest of the output.

`-dN'
     Like `-dD' except that the macro arguments and contents are
     omitted.  Only `#define NAME' is included in the output.

`-trigraphs'
     Support ANSI C trigraphs.  The `-ansi' option also has this effect.

`-Wp,OPTION'
     Pass OPTION as an option to the preprocessor.  If OPTION contains
     commas, it is split into multiple options at the commas.


File: ^.!gcc.docs.pascal.gpc,  Node: Assembler Options,  Next: Link Options,  Prev: Preprocessor Options,  Up: Invoking GPC

Passing Options to the Assembler
================================

   You can pass options to the assembler.

`-Wa,OPTION'
     Pass OPTION as an option to the assembler.  If OPTION contains
     commas, it is split into multiple options at the commas.


File: ^.!gcc.docs.pascal.gpc,  Node: Link Options,  Next: Directory Options,  Prev: Assembler Options,  Up: Invoking GPC

Options for Linking
===================

   These options come into play when the compiler links object files
into an executable output file.  They are meaningless if the compiler is
not doing a link step.

`OBJECT-FILE-NAME'
     A file name that does not end in a special recognized suffix is
     considered to name an object file or library.  (Object files are
     distinguished from libraries by the linker according to the file
     contents.)  If linking is done, these object files are used as
     input to the linker.

`-c'
`-S'
`-E'
     If any of these options is used, then the linker is not run, and
     object file names should not be used as arguments.  *Note Overall
     Options::.

`-lLIBRARY'
     Search the library named LIBRARY when linking.

     It makes a difference where in the command you write this option;
     the linker searches processes libraries and object files in the
     order they are specified.  Thus, `foo.o -lz bar.o' searches
     library `z' after file `foo.o' but before `bar.o'.  If `bar.o'
     refers to functions in `z', those functions may not be loaded.

     The linker searches a standard list of directories for the library,
     which is actually a file named `libLIBRARY.a'.  The linker then
     uses this file as if it had been specified precisely by name.

     The directories searched include several standard system
     directories plus any that you specify with `-L'.

     Normally the files found this way are library files--archive files
     whose members are object files.  The linker handles an archive
     file by scanning through it for members which define symbols that
     have so far been referenced but not defined.  But if the file that
     is found is an ordinary object file, it is linked in the usual
     fashion.  The only difference between using an `-l' option and
     specifying a file name is that `-l' surrounds LIBRARY with `lib'
     and `.a' and searches several directories.

`-lobjc'
     You need this special case of the `-l' option in order to link an
     Objective C program.

`-nostartfiles'
     Do not use the standard system startup files when linking.  The
     standard system libraries are used normally, unless `-nostdlib' or
     `-nodefaultlibs' is used.

`-nodefaultlibs'
     Do not use the standard system libraries when linking.  Only the
     libraries you specify will be passed to the linker.  The standard
     startup files are used normally, unless `-nostartfiles' is used.

`-nostdlib'
     Do not use the standard system startup files or libraries when
     linking.  No startup files and only the libraries you specify will
     be passed to the linker.

     One of the standard libraries bypassed by `-nostdlib' and
     `-nodefaultlibs' is `libgcc.a', a library of internal subroutines
     that GNU Pascal uses to overcome shortcomings of particular
     machines, or special needs for some languages.  In most cases, you
     need `libgcc.a' even when you want to avoid other standard
     libraries.  In other words, when you specify `-nostdlib' or
     `-nodefaultlibs' you should usually specify `-lgcc' as well.  This
     ensures that you have no unresolved references to internal GNU
     Pascal library subroutines.  (For example, `__main', used to
     ensure C++ constructors will be called;

`-s'
     Remove all symbol table and relocation information from the
     executable.

`-static'
     On systems that support dynamic linking, this prevents linking
     with the shared libraries.  On other systems, this option has no
     effect.

`-shared'
     Produce a shared object which can then be linked with other
     objects to form an executable.  Only a few systems support this
     option.

`-symbolic'
     Bind references to global symbols when building a shared object.
     Warn about any unresolved references (unless overridden by the
     link editor option `-Xlinker -z -Xlinker defs').  Only a few
     systems support this option.

`-Xlinker OPTION'
     Pass OPTION as an option to the linker.  You can use this to
     supply system-specific linker options which GNU Pascal does not
     know how to recognize.

     If you want to pass an option that takes an argument, you must use
     `-Xlinker' twice, once for the option and once for the argument.
     For example, to pass `-assert definitions', you must write
     `-Xlinker -assert -Xlinker definitions'.  It does not work to write
     `-Xlinker "-assert definitions"', because this passes the entire
     string as a single argument, which is not what the linker expects.

`-Wl,OPTION'
     Pass OPTION as an option to the linker.  If OPTION contains
     commas, it is split into multiple options at the commas.

`-u SYMBOL'
     Pretend the symbol SYMBOL is undefined, to force linking of
     library modules to define it.  You can use `-u' multiple times with
     different symbols to force loading of additional library modules.


File: ^.!gcc.docs.pascal.gpc,  Node: Directory Options,  Next: Target Options,  Prev: Link Options,  Up: Invoking GPC

Options for Directory Search
============================

   These options specify directories to search for header files, for
libraries and for parts of the compiler:

`-IDIR'
     Add the directory DIRECTORY to the head of the list of directories
     to be searched for header files.  This can be used to override a
     system header file, substituting your own version, since these
     directories are searched before the system header file
     directories.  If you use more than one `-I' option, the
     directories are scanned in left-to-right order; the standard
     system directories come after.

`-I-'
     Any directories you specify with `-I' options before the `-I-'
     option are searched only for the case of `#include "FILE"'; they
     are not searched for `#include <FILE>'.

     If additional directories are specified with `-I' options after
     the `-I-', these directories are searched for all `#include'
     directives.  (Ordinarily *all* `-I' directories are used this way.)

     In addition, the `-I-' option inhibits the use of the current
     directory (where the current input file came from) as the first
     search directory for `#include "FILE"'.  There is no way to
     override this effect of `-I-'.  With `-I.' you can specify
     searching the directory which was current when the compiler was
     invoked.  That is not exactly the same as what the preprocessor
     does by default, but it is often satisfactory.

     `-I-' does not inhibit the use of the standard system directories
     for header files.  Thus, `-I-' and `-nostdinc' are independent.

`-LDIR'
     Add directory DIR to the list of directories to be searched for
     `-l'.

`-BPREFIX'
     This option specifies where to find the executables, libraries,
     include files, and data files of the compiler itself.

     The compiler driver program runs one or more of the subprograms
     `cpp', `cc1', `as' and `ld'.  It tries PREFIX as a prefix for each
     program it tries to run, both with and without `MACHINE/VERSION/'
     (*note Target Options::.).

     For each subprogram to be run, the compiler driver first tries the
     `-B' prefix, if any.  If that name is not found, or if `-B' was
     not specified, the driver tries two standard prefixes, which are
     `/usr/lib/gcc/' and `/usr/local/lib/gcc-lib/'.  If neither of
     those results in a file name that is found, the unmodified program
     name is searched for using the directories specified in your
     `PATH' environment variable.

     `-B' prefixes that effectively specify directory names also apply
     to libraries in the linker, because the compiler translates these
     options into `-L' options for the linker.  They also apply to
     includes files in the preprocessor, because the compiler
     translates these options into `-isystem' options for the
     preprocessor.  In this case, the compiler appends `include' to the
     prefix.

     The run-time support file `libgcc.a' can also be searched for using
     the `-B' prefix, if needed.  If it is not found there, the two
     standard prefixes above are tried, and that is all.  The file is
     left out of the link if it is not found by those means.

     Another way to specify a prefix much like the `-B' prefix is to use
     the environment variable `GPC_EXEC_PREFIX'.  *Note Environment
     Variables::.


File: ^.!gcc.docs.pascal.gpc,  Node: Target Options,  Next: Submodel Options,  Prev: Directory Options,  Up: Invoking GPC

Specifying Target Machine and Compiler Version
==============================================

   By default, GNU Pascal compiles code for the same type of machine
that you are using.  However, it can also be installed as a
cross-compiler, to compile for some other type of machine.  In fact,
several different configurations of GNU Pascal, for different target
machines, can be installed side by side.  Then you specify which one to
use with the `-b' option.

   In addition, older and newer versions of GNU Pascal can be installed
side by side.  One of them (probably the newest) will be the default,
but you may sometimes wish to use another.

`-b MACHINE'
     The argument MACHINE specifies the target machine for compilation.
     This is useful when you have installed GNU Pascal as a
     cross-compiler.

     The value to use for MACHINE is the same as was specified as the
     machine type when configuring GNU Pascal as a cross-compiler.  For
     example, if a cross-compiler was configured with `configure
     i386v', meaning to compile for an 80386 running System V, then you
     would specify `-b i386v' to run that cross compiler.

     When you do not specify `-b', it normally means to compile for the
     same type of machine that you are using.

`-V VERSION'
     The argument VERSION specifies which version of GNU Pascal to run.
     This is useful when multiple versions are installed.  For example,
     VERSION might be `2.0', meaning to run GNU Pascal version 2.0.

     The default version, when you do not specify `-V', is the last
     version of GNU Pascal that you installed.

   The `-b' and `-V' options actually work by controlling part of the
file name used for the executable files and libraries used for
compilation.  A given version of GNU Pascal, for a given target
machine, is normally kept in the directory
`/usr/local/lib/gcc-lib/MACHINE/VERSION'.

   Thus, sites can customize the effect of `-b' or `-V' either by
changing the names of these directories or adding alternate names (or
symbolic links).  If in directory `/usr/local/lib/gcc-lib/' the file
`80386' is a link to the file `i386v', then `-b 80386' becomes an alias
for `-b i386v'.

   In one respect, the `-b' or `-V' do not completely change to a
different compiler: the top-level driver program `gpc' that you
originally invoked continues to run and invoke the other executables
(preprocessor, compiler per se, assembler and linker) that do the real
work.  However, since no real work is done in the driver program, it
usually does not matter that the driver program in use is not the one
for the specified target and version.

   The only way that the driver program depends on the target machine is
in the parsing and handling of special machine-specific options.
However, this is controlled by a file which is found, along with the
other executables, in the directory for the specified version and
target machine.  As a result, a single installed driver program adapts
to any specified target machine and compiler version.

   The driver program executable does control one significant thing,
however: the default version and target machine.  Therefore, you can
install different instances of the driver program, compiled for
different targets or versions, under different names.

   For example, if the driver for version 2.0 is installed as `ogcc'
and that for version 2.1 is installed as `gpc', then the command `gpc'
will use version 2.1 by default, while `ogcc' will use 2.0 by default.
However, you can choose either version with either command with the
`-V' option.


File: ^.!gcc.docs.pascal.gpc,  Node: Submodel Options,  Next: Environment Variables,  Prev: Target Options,  Up: Invoking GPC

Hardware Models and Configurations
==================================

   Earlier we discussed the standard option `-b' which chooses among
different installed compilers for completely different target machines,
such as Vax vs. 68000 vs. 80386.

   In addition, each of these target machine types can have its own
special options, starting with `-m', to choose among various hardware
models or configurations--for example, 68010 vs 68020, floating
coprocessor or none.  A single installed version of the compiler can
compile for any model or configuration, according to the options
specified.

   Some configurations of the compiler also support additional special
options, usually for compatibility with other compilers on the same
platform.

* Menu:

* M680x0 Options::
* VAX Options::
* SPARC Options::
* Convex Options::
* AMD29K Options::
* ARM Options::
* M88K Options::
* RS/6000 and PowerPC Options::
* RT Options::
* MIPS Options::
* i386 Options::
* HPPA Options::
* Intel 960 Options::
* DEC Alpha Options::
* Clipper Options::
* H8/300 Options::
* System V Options::


File: ^.!gcc.docs.pascal.gpc,  Node: M680x0 Options,  Next: VAX Options,  Up: Submodel Options

M680x0 Options
--------------

   These are the `-m' options defined for the 68000 series.  The default
values for these options depends on which style of 68000 was selected
when the compiler was configured; the defaults for the most common
choices are given below.

`-m68000'
`-mc68000'
     Generate output for a 68000.  This is the default when the
     compiler is configured for 68000-based systems.

`-m68020'
`-mc68020'
     Generate output for a 68020.  This is the default when the
     compiler is configured for 68020-based systems.

`-m68881'
     Generate output containing 68881 instructions for floating point.
     This is the default for most 68020 systems unless `-nfp' was
     specified when the compiler was configured.

`-m68030'
     Generate output for a 68030.  This is the default when the
     compiler is configured for 68030-based systems.

`-m68040'
     Generate output for a 68040.  This is the default when the
     compiler is configured for 68040-based systems.

     This option inhibits the use of 68881/68882 instructions that have
     to be emulated by software on the 68040.  If your 68040 does not
     have code to emulate those instructions, use `-m68040'.

`-m68020-40'
     Generate output for a 68040, without using any of the new
     instructions.  This results in code which can run relatively
     efficiently on either a 68020/68881 or a 68030 or a 68040.  The
     generated code does use the 68881 instructions that are emulated
     on the 68040.

`-mfpa'
     Generate output containing Sun FPA instructions for floating point.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not available for all m68k
     targets.  Normally the facilities of the machine's usual C
     compiler are used, but this can't be done directly in
     cross-compilation.  You must make your own arrangements to provide
     suitable library functions for cross-compilation.  The embedded
     targets `m68k-*-aout' and `m68k-*-coff' do provide software
     floating point support.

`-mshort'
     Consider type `int' to be 16 bits wide, like `short int'.

`-mnobitfield'
     Do not use the bit-field instructions.  The `-m68000' option
     implies `-mnobitfield'.

`-mbitfield'
     Do use the bit-field instructions.  The `-m68020' option implies
     `-mbitfield'.  This is the default if you use a configuration
     designed for a 68020.

`-mrtd'
     Use a different function-calling convention, in which functions
     that take a fixed number of arguments return with the `rtd'
     instruction, which pops their arguments while returning.  This
     saves one instruction in the caller since there is no need to pop
     the arguments there.

     This calling convention is incompatible with the one normally used
     on Unix, so you cannot use it if you need to call libraries
     compiled with the Unix compiler.

     Also, you must provide function prototypes for all functions that
     take variable numbers of arguments (including `printf'); otherwise
     incorrect code will be generated for calls to those functions.

     In addition, seriously incorrect code will result if you call a
     function with too many arguments.  (Normally, extra arguments are
     harmlessly ignored.)

     The `rtd' instruction is supported by the 68010 and 68020
     processors, but not by the 68000.


File: ^.!gcc.docs.pascal.gpc,  Node: VAX Options,  Next: SPARC Options,  Prev: M680x0 Options,  Up: Submodel Options

VAX Options
-----------

   These `-m' options are defined for the Vax:

`-munix'
     Do not output certain jump instructions (`aobleq' and so on) that
     the Unix assembler for the Vax cannot handle across long ranges.

`-mgnu'
     Do output those jump instructions, on the assumption that you will
     assemble with the GNU assembler.

`-mg'
     Output code for g-format floating point numbers instead of
     d-format.


File: ^.!gcc.docs.pascal.gpc,  Node: SPARC Options,  Next: Convex Options,  Prev: VAX Options,  Up: Submodel Options

SPARC Options
-------------

   These `-m' switches are supported on the SPARC:

`-mno-app-regs'
`-mapp-regs'
     Specify `-mapp-regs' to generate output using the global registers
     2 through 4, which the SPARC SVR4 ABI reserves for applications.
     This is the default.

     To be fully SVR4 ABI compliant at the cost of some performance
     loss, specify `-mno-app-regs'.  You should compile libraries and
     system software with this option.

`-mfpu'
`-mhard-float'
     Generate output containing floating point instructions.  This is
     the default.

`-mno-fpu'
`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not available for all SPARC
     targets.  Normally the facilities of the machine's usual C
     compiler are used, but this cannot be done directly in
     cross-compilation.  You must make your own arrangements to provide
     suitable library functions for cross-compilation.  The embedded
     targets `sparc-*-aout' and `sparclite-*-*' do provide software
     floating point support.

     `-msoft-float' changes the calling convention in the output file;
     therefore, it is only useful if you compile *all* of a program with
     this option.  In particular, you need to compile `libgcc.a', the
     library that comes with GNU Pascal, with `-msoft-float' in order
     for this to work.

`-mhard-quad-float'
     Generate output containing quad-word (long double) floating point
     instructions.

`-msoft-quad-float'
     Generate output containing library calls for quad-word (long
     double) floating point instructions.  The functions called are
     those specified in the SPARC ABI.  This is the default.

     As of this writing, there are no sparc implementations that have
     hardware support for the quad-word floating point instructions.
     They all invoke a trap handler for one of these instructions, and
     then the trap handler emulates the effect of the instruction.
     Because of the trap handler overhead, this is much slower than
     calling the ABI library routines.  Thus the `-msoft-quad-float'
     option is the default.

`-mno-epilogue'
`-mepilogue'
     With `-mepilogue' (the default), the compiler always emits code for
     function exit at the end of each function.  Any function exit in
     the middle of the function (such as a return statement in C) will
     generate a jump to the exit code at the end of the function.

     With `-mno-epilogue', the compiler tries to emit exit code inline
     at every function exit.

`-mno-flat'
`-mflat'
     With `-mflat', the compiler does not generate save/restore
     instructions and will use a "flat" or single register window
     calling convention.  This model uses %i7 as the frame pointer and
     is compatible with the normal register window model.  Code from
     either may be intermixed although debugger support is still
     incomplete.  The local registers and the input registers (0-5) are
     still treated as "call saved" registers and will be saved on the
     stack as necessary.

     With `-mno-flat' (the default), the compiler emits save/restore
     instructions (except for leaf functions) and is the normal mode of
     operation.

`-mno-unaligned-doubles'
`-munaligned-doubles'
     Assume that doubles have 8 byte alignment.  This is the default.

     With `-munaligned-doubles', GNU Pascal assumes that doubles have 8
     byte alignment only if they are contained in another type, or if
     they have an absolute address.  Otherwise, it assumes they have 4
     byte alignment.  Specifying this option avoids some rare
     compatibility problems with code generated by other compilers.  It
     is not the default because it results in a performance loss,
     especially for floating point code.

`-mv8'
`-msparclite'
     These two options select variations on the SPARC architecture.

     By default (unless specifically configured for the Fujitsu
     SPARClite), GPC generates code for the v7 variant of the SPARC
     architecture.

     `-mv8' will give you SPARC v8 code.  The only difference from v7
     code is that the compiler emits the integer multiply and integer
     divide instructions which exist in SPARC v8 but not in SPARC v7.

     `-msparclite' will give you SPARClite code.  This adds the integer
     multiply, integer divide step and scan (`ffs') instructions which
     exist in SPARClite but not in SPARC v7.

`-mcypress'
`-msupersparc'
     These two options select the processor for which the code is
     optimised.

     With `-mcypress' (the default), the compiler optimizes code for the
     Cypress CY7C602 chip, as used in the SparcStation/SparcServer 3xx
     series.  This is also appropriate for the older SparcStation 1, 2,
     IPX etc.

     With `-msupersparc' the compiler optimizes code for the SuperSparc
     cpu, as used in the SparcStation 10, 1000 and 2000 series. This
     flag also enables use of the full SPARC v8 instruction set.

   In a future version of GPC, these options will very likely be
renamed to `-mcpu=cypress' and `-mcpu=supersparc'.

   These `-m' switches are supported in addition to the above on SPARC
V9 processors:

`-mmedlow'
     Generate code for the Medium/Low code model: assume a 32 bit
     address space.  Programs are statically linked, PIC is not
     supported.  Pointers are still 64 bits.

     It is very likely that a future version of GPC will rename this
     option.

`-mmedany'
     Generate code for the Medium/Anywhere code model: assume a 32 bit
     text segment starting at offset 0, and a 32 bit data segment
     starting anywhere (determined at link time).  Programs are
     statically linked, PIC is not supported.  Pointers are still 64
     bits.

     It is very likely that a future version of GPC will rename this
     option.

`-mint64'
     Types long and int are 64 bits.

`-mlong32'
     Types long and int are 32 bits.

`-mlong64'
`-mint32'
     Type long is 64 bits, and type int is 32 bits.

`-mstack-bias'
`-mno-stack-bias'
     With `-mstack-bias', GNU Pascal assumes that the stack pointer, and
     frame pointer if present, are offset by -2047 which must be added
     back when making stack frame references.  Otherwise, assume no
     such offset is present.


File: ^.!gcc.docs.pascal.gpc,  Node: Convex Options,  Next: AMD29K Options,  Prev: SPARC Options,  Up: Submodel Options

Convex Options
--------------

   These `-m' options are defined for Convex:

`-mc1'
     Generate output for C1.  The code will run on any Convex machine.
     The preprocessor symbol `__convex__c1__' is defined.

`-mc2'
     Generate output for C2.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C2.  The preprocessor symbol `__convex_c2__' is defined.

`-mc32'
     Generate output for C32xx.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C32.  The preprocessor symbol `__convex_c32__' is defined.

`-mc34'
     Generate output for C34xx.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C34.  The preprocessor symbol `__convex_c34__' is defined.

`-mc38'
     Generate output for C38xx.  Uses instructions not available on C1.
     Scheduling and other optimizations are chosen for max performance
     on C38.  The preprocessor symbol `__convex_c38__' is defined.

`-margcount'
     Generate code which puts an argument count in the word preceding
     each argument list.  This is compatible with regular CC, and a few
     programs may need the argument count word.  GDB and other
     source-level debuggers do not need it; this info is in the symbol
     table.

`-mnoargcount'
     Omit the argument count word.  This is the default.

`-mvolatile-cache'
     Allow volatile references to be cached.  This is the default.

`-mvolatile-nocache'
     Volatile references bypass the data cache, going all the way to
     memory.  This is only needed for multi-processor code that does
     not use standard synchronization instructions.  Making
     non-volatile references to volatile locations will not necessarily
     work.

`-mlong32'
     Type long is 32 bits, the same as type int.  This is the default.

`-mlong64'
     Type long is 64 bits, the same as type long long.  This option is
     useless, because no library support exists for it.


File: ^.!gcc.docs.pascal.gpc,  Node: AMD29K Options,  Next: ARM Options,  Prev: Convex Options,  Up: Submodel Options

AMD29K Options
--------------

   These `-m' options are defined for the AMD Am29000:

`-mdw'
     Generate code that assumes the `DW' bit is set, i.e., that byte and
     halfword operations are directly supported by the hardware.  This
     is the default.

`-mndw'
     Generate code that assumes the `DW' bit is not set.

`-mbw'
     Generate code that assumes the system supports byte and halfword
     write operations.  This is the default.

`-mnbw'
     Generate code that assumes the systems does not support byte and
     halfword write operations.  `-mnbw' implies `-mndw'.

`-msmall'
     Use a small memory model that assumes that all function addresses
     are either within a single 256 KB segment or at an absolute
     address of less than 256k.  This allows the `call' instruction to
     be used instead of a `const', `consth', `calli' sequence.

`-mnormal'
     Use the normal memory model: Generate `call' instructions only when
     calling functions in the same file and `calli' instructions
     otherwise.  This works if each file occupies less than 256 KB but
     allows the entire executable to be larger than 256 KB.  This is
     the default.

`-mlarge'
     Always use `calli' instructions.  Specify this option if you expect
     a single file to compile into more than 256 KB of code.

`-m29050'
     Generate code for the Am29050.

`-m29000'
     Generate code for the Am29000.  This is the default.

`-mkernel-registers'
     Generate references to registers `gr64-gr95' instead of to
     registers `gr96-gr127'.  This option can be used when compiling
     kernel code that wants a set of global registers disjoint from
     that used by user-mode code.

     Note that when this option is used, register names in `-f' flags
     must use the normal, user-mode, names.

`-muser-registers'
     Use the normal set of global registers, `gr96-gr127'.  This is the
     default.

`-mstack-check'
`-mno-stack-check'
     Insert (or do not insert) a call to `__msp_check' after each stack
     adjustment.  This is often used for kernel code.

`-mstorem-bug'
`-mno-storem-bug'
     `-mstorem-bug' handles 29k processors which cannot handle the
     separation of a mtsrim insn and a storem instruction (most 29000
     chips to date, but not the 29050).

`-mno-reuse-arg-regs'
`-mreuse-arg-regs'
     `-mno-reuse-arg-regs' tells the compiler to only use incoming
     argument registers for copying out arguments.  This helps detect
     calling a function with fewer arguments than it was declared with.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not part of GNU Pascal.
     Normally the facilities of the machine's usual C compiler are
     used, but this can't be done directly in cross-compilation.  You
     must make your own arrangements to provide suitable library
     functions for cross-compilation.


File: ^.!gcc.docs.pascal.gpc,  Node: ARM Options,  Next: M88K Options,  Prev: AMD29K Options,  Up: Submodel Options

ARM Options
-----------

   These `-m' options are defined for Advanced RISC Machines (ARM)
architectures:

`-m2'
`-m3'
     These options are identical.  Generate code for the ARM2 and ARM3
     processors.  This option is the default.  You should also use this
     option to generate code for ARM6 processors that are running with a
     26-bit program counter.

`-m6'
     Generate code for the ARM6 processor when running with a 32-bit
     program counter.

`-mapcs'
     Generate a stack frame that is compliant with the ARM Procedure
     Call Standard for all functions, even if this is not strictly
     necessary for correct execution of the code.

`-mbsd'
     This option only applies to RISC iX.  Emulate the native BSD-mode
     compiler.  This is the default if `-ansi' is not specified.

`-mxopen'
     This option only applies to RISC iX.  Emulate the native
     X/Open-mode compiler.

`-mno-symrename'
     This option only applies to RISC iX.  Do not run the assembler
     post-processor, `symrename', after code has been assembled.
     Normally it is necessary to modify some of the standard symbols in
     preparation for linking with the RISC iX C library; this option
     suppresses this pass.  The post-processor is never run when the
     compiler is built for cross-compilation.


File: ^.!gcc.docs.pascal.gpc,  Node: M88K Options,  Next: RS/6000 and PowerPC Options,  Prev: ARM Options,  Up: Submodel Options

M88K Options
------------

   These `-m' options are defined for Motorola 88k architectures:

`-m88000'
     Generate code that works well on both the m88100 and the m88110.

`-m88100'
     Generate code that works best for the m88100, but that also runs
     on the m88110.

`-m88110'
     Generate code that works best for the m88110, and may not run on
     the m88100.

`-mbig-pic'
     Obsolete option to be removed from the next revision.  Use `-fPIC'.

`-midentify-revision'
     Include an `ident' directive in the assembler output recording the
     source file name, compiler name and version, timestamp, and
     compilation flags used.

`-mno-underscores'
     In assembler output, emit symbol names without adding an underscore
     character at the beginning of each name.  The default is to use an
     underscore as prefix on each name.

`-mocs-debug-info'
`-mno-ocs-debug-info'
     Include (or omit) additional debugging information (about
     registers used in each stack frame) as specified in the 88open
     Object Compatibility Standard, "OCS".  This extra information
     allows debugging of code that has had the frame pointer
     eliminated.  The default for DG/UX, SVr4, and Delta 88 SVr3.2 is
     to include this information; other 88k configurations omit this
     information by default.

`-mocs-frame-position'
     When emitting COFF debugging information for automatic variables
     and parameters stored on the stack, use the offset from the
     canonical frame address, which is the stack pointer (register 31)
     on entry to the function.  The DG/UX, SVr4, Delta88 SVr3.2, and
     BCS configurations use `-mocs-frame-position'; other 88k
     configurations have the default `-mno-ocs-frame-position'.

`-mno-ocs-frame-position'
     When emitting COFF debugging information for automatic variables
     and parameters stored on the stack, use the offset from the frame
     pointer register (register 30).  When this option is in effect,
     the frame pointer is not eliminated when debugging information is
     selected by the -g switch.

`-moptimize-arg-area'
`-mno-optimize-arg-area'
     Control how function arguments are stored in stack frames.
     `-moptimize-arg-area' saves space by optimizing them, but this
     conflicts with the 88open specifications.  The opposite
     alternative, `-mno-optimize-arg-area', agrees with 88open
     standards.  By default GNU Pascal does not optimize the argument
     area.

`-mshort-data-NUM'
     Generate smaller data references by making them relative to `r0',
     which allows loading a value using a single instruction (rather
     than the usual two).  You control which data references are
     affected by specifying NUM with this option.  For example, if you
     specify `-mshort-data-512', then the data references affected are
     those involving displacements of less than 512 bytes.
     `-mshort-data-NUM' is not effective for NUM greater than 64k.

`-mserialize-volatile'
`-mno-serialize-volatile'
     Do, or don't, generate code to guarantee sequential consistency of
     volatile memory references.  By default, consistency is guaranteed.

     The order of memory references made by the MC88110 processor does
     not always match the order of the instructions requesting those
     references.  In particular, a load instruction may execute before
     a preceding store instruction.  Such reordering violates
     sequential consistency of volatile memory references, when there
     are multiple processors.   When consistency must be guaranteed,
     GNU Pascal generates special instructions, as needed, to force
     execution in the proper order.

     The MC88100 processor does not reorder memory references and so
     always provides sequential consistency.  However, by default, GNU
     C generates the special instructions to guarantee consistency even
     when you use `-m88100', so that the code may be run on an MC88110
     processor.  If you intend to run your code only on the MC88100
     processor, you may use `-mno-serialize-volatile'.

     The extra code generated to guarantee consistency may affect the
     performance of your application.  If you know that you can safely
     forgo this guarantee, you may use `-mno-serialize-volatile'.

`-msvr4'
`-msvr3'
     Turn on (`-msvr4') or off (`-msvr3') compiler extensions related
     to System V release 4 (SVr4).  This controls the following:

       1. Which variant of the assembler syntax to emit.

       2. `-msvr4' makes the Pascal preprocessor recognize `#pragma
          weak' that is used on System V release 4.

       3. `-msvr4' makes GNU Pascal issue additional declaration
          directives used in SVr4.

     `-msvr4' is the default for the m88k-motorola-sysv4 and
     m88k-dg-dgux m88k configurations. `-msvr3' is the default for all
     other m88k configurations.

`-mversion-03.00'
     This option is obsolete, and is ignored.

`-mno-check-zero-division'
`-mcheck-zero-division'
     Do, or don't, generate code to guarantee that integer division by
     zero will be detected.  By default, detection is guaranteed.

     Some models of the MC88100 processor fail to trap upon integer
     division by zero under certain conditions.  By default, when
     compiling code that might be run on such a processor, GNU C
     generates code that explicitly checks for zero-valued divisors and
     traps with exception number 503 when one is detected.  Use of
     mno-check-zero-division suppresses such checking for code
     generated to run on an MC88100 processor.

     GNU Pascal assumes that the MC88110 processor correctly detects all
     instances of integer division by zero.  When `-m88110' is
     specified, both `-mcheck-zero-division' and
     `-mno-check-zero-division' are ignored, and no explicit checks for
     zero-valued divisors are generated.

`-muse-div-instruction'
     Use the div instruction for signed integer division on the MC88100
     processor.  By default, the div instruction is not used.

     On the MC88100 processor the signed integer division instruction
     div) traps to the operating system on a negative operand.  The
     operating system transparently completes the operation, but at a
     large cost in execution time.  By default, when compiling code
     that might be run on an MC88100 processor, GNU Pascal emulates
     signed integer division using the unsigned integer division
     instruction divu), thereby avoiding the large penalty of a trap to
     the operating system.  Such emulation has its own, smaller,
     execution cost in both time and space.  To the extent that your
     code's important signed integer division operations are performed
     on two nonnegative operands, it may be desirable to use the div
     instruction directly.

     On the MC88110 processor the div instruction (also known as the
     divs instruction) processes negative operands without trapping to
     the operating system.  When `-m88110' is specified,
     `-muse-div-instruction' is ignored, and the div instruction is used
     for signed integer division.

     Note that the result of dividing INT_MIN by -1 is undefined.  In
     particular, the behavior of such a division with and without
     `-muse-div-instruction'  may differ.

`-mtrap-large-shift'
`-mhandle-large-shift'
     Include code to detect bit-shifts of more than 31 bits;
     respectively, trap such shifts or emit code to handle them
     properly.  By default GNU Pascal makes no special provision for
     large bit shifts.

`-mwarn-passed-structs'
     Warn when a function passes a struct as an argument or result.
     Structure-passing conventions have changed during the evolution of
     the C language, and are often the source of portability problems.
     By default, GNU Pascal issues no such warning.


File: ^.!gcc.docs.pascal.gpc,  Node: RS/6000 and PowerPC Options,  Next: RT Options,  Prev: M88K Options,  Up: Submodel Options

IBM RS/6000 and PowerPC Options
-------------------------------

   These `-m' options are defined for the IBM RS/6000 and PowerPC:
`-mpower'
`-mno-power'
`-mpower2'
`-mno-power2'
`-mpowerpc'
`-mno-powerpc'
`-mpowerpc-gpopt'
`-mno-powerpc-gpopt'
`-mpowerpc-gfxopt'
`-mno-powerpc-gfxopt'
     GNU Pascal supports two related instruction set architectures for
     the RS/6000 and PowerPC.  The "POWER" instruction set are those
     instructions supported by the `rios' chip set used in the original
     RS/6000 systems and the "PowerPC" instruction set is the
     architecture of the Motorola MPC6xx microprocessors.  The PowerPC
     architecture defines 64-bit instructions, but they are not
     supported by any current processors.

     Neither architecture is a subset of the other.  However there is a
     large common subset of instructions supported by both.  An MQ
     register is included in processors supporting the POWER
     architecture.

     You use these options to specify which instructions are available
     on the processor you are using.  The default value of these
     options is determined when configuring GNU Pascal.  Specifying the
     `-mcpu=CPU_TYPE' overrides the specification of these options.  We
     recommend you use that option rather than these.

     The `-mpower' option allows GNU Pascal to generate instructions
     that are found only in the POWER architecture and to use the MQ
     register.  Specifying `-mpower2' implies `-power' and also allows
     GNU Pascal to generate instructions that are present in the POWER2
     architecture but not the original POWER architecture.

     The `-mpowerpc' option allows GNU Pascal to generate instructions
     that are found only in the 32-bit subset of the PowerPC
     architecture.  Specifying `-mpowerpc-gpopt' implies `-mpowerpc'
     and also allows GNU Pascal to use the optional PowerPC
     architecture instructions in the General Purpose group, including
     floating-point square root.  Specifying `-mpowerpc-gfxopt' implies
     `-mpowerpc' and also allows GNU Pascal to use the optional PowerPC
     architecture instructions in the Graphics group, including
     floating-point select.

     If you specify both `-mno-power' and `-mno-powerpc', GNU Pascal
     will use only the instructions in the common subset of both
     architectures plus some special AIX common-mode calls, and will
     not use the MQ register.  Specifying both `-mpower' and `-mpowerpc'
     permits GNU Pascal to use any instruction from either architecture
     and to allow use of the MQ register; specify this for the Motorola
     MPC601.

`-mnew-mnemonics'
`-mold-mnemonics'
     Select which mnemonics to use in the generated assembler code.
     `-mnew-mnemonics' requests output that uses the assembler mnemonics
     defined for the PowerPC architecture, while `-mold-mnemonics'
     requests the assembler mnemonics defined for the POWER
     architecture.  Instructions defined in only one architecture have
     only one mnemonic; GNU Pascal uses that mnemonic irrespective of
     which of these options is specified.

     PowerPC assemblers support both the old and new mnemonics, as will
     later POWER assemblers.  Current POWER assemblers only support the
     old mnemonics.  Specify `-mnew-mnemonics' if you have an assembler
     that supports them, otherwise specify `-mold-mnemonics'.

     The default value of these options depends on how GNU Pascal was
     configured.  Specifying `-mcpu=CPU_TYPE' sometimes overrides the
     value of these option.  Unless you are building a cross-compiler,
     you should normally not specify either `-mnew-mnemonics' or
     `-mold-mnemonics', but should instead accept the default.

`-mcpu=CPU_TYPE'
     Set architecture type, register usage, choice of mnemonics, and
     instruction scheduling parameters for machine type CPU_TYPE.  By
     default, CPU_TYPE is the target system defined when GNU Pascal was
     configured.  Supported values for CPU_TYPE are `rios1', `rios2',
     `rsc', `601', `603', `604', `power', `powerpc', `403', and
     `common'.  `-mcpu=power' and `-mcpu=powerpc' specify generic POWER
     and pure PowerPC (i.e., not MPC601) architecture machine types,
     with an appropriate, generic processor model assumed for
     scheduling purposes.

     Specifying `-mcpu=rios1', `-mcpu=rios2', `-mcpu=rsc', or
     `-mcpu=power' enables the `-mpower' option and disables the
     `-mpowerpc' option; `-mcpu=601' enables both the `-mpower' and
     `-mpowerpc' options; `-mcpu=603', `-mcpu=604', `-mcpu=403', and
     `-mcpu=powerpc' enable the `-mpowerpc' option and disable the
     `-mpower' option; `-mcpu=common' disables both the `-mpower' and
     `-mpowerpc' options.

     To generate code that will operate on all members of the RS/6000
     and PowerPC families, specify `-mcpu=common'.  In that case, GNU
     Pascal will use only the instructions in the common subset of both
     architectures plus some special AIX common-mode calls, and will
     not use the MQ register.  GNU Pascal assumes a generic processor
     model for scheduling purposes.

     Specifying `-mcpu=rios1', `-mcpu=rios2', `-mcpu=rsc', or
     `-mcpu=power' also disables the `new-mnemonics' option.
     Specifying `-mcpu=601', `-mcpu=603', `-mcpu=604', `403', or
     `-mcpu=powerpc' also enables the `new-mnemonics' option.

`-mfull-toc'
`-mno-fp-in-toc'
`-mno-sum-in-toc'
`-mminimal-toc'
     Modify generation of the TOC (Table Of Contents), which is created
     for every executable file.  The `-mfull-toc' option is selected by
     default.  In that case, GNU Pascal will allocate at least one TOC
     entry for each unique non-automatic variable reference in your
     program.  GNU Pascal will also place floating-point constants in
     the TOC.  However, only 16,384 entries are available in the TOC.

     If you receive a linker error message that saying you have
     overflowed the available TOC space, you can reduce the amount of
     TOC space used with the `-mno-fp-in-toc' and `-mno-sum-in-toc'
     options.  `-mno-fp-in-toc' prevents GNU Pascal from putting
     floating-point constants in the TOC and `-mno-sum-in-toc' forces
     GNU Pascal to generate code to calculate the sum of an address and
     a constant at run-time instead of putting that sum into the TOC.
     You may specify one or both of these options.  Each causes GNU
     Pascal to produce very slightly slower and larger code at the
     expense of conserving TOC space.

     If you still run out of space in the TOC even when you specify
     both of these options, specify `-mminimal-toc' instead.  This
     option causes GNU Pascal to make only one TOC entry for every
     file.  When you specify this option, GNU Pascal will produce code
     that is slower and larger but which uses extremely little TOC
     space.  You may wish to use this option only on files that contain
     less frequently executed code.

`-msoft-float'
`-mhard-float'
     Generate code that does not use (uses) the floating-point register
     set.  Software floating point emulation is provided if you use the
     `-msoft-float' option, and pass the option to GNU Pascal when
     linking.

`-mmultiple'
`-mno-multiple'
     Generate code that uses (does not use) the load multiple word
     instructions and the store multiple word instructions.  These
     instructions are generated by default on POWER systems, and not
     generated on PowerPC systems.  Do not use `-mmultiple' on little
     endian PowerPC systems, since those instructions do not work when
     the processor is in little endian mode.

`-mstring'
`-mno-string'
     Generate code that uses (does not use) the load string
     instructions and the store string word instructions to save
     multiple registers and do small block moves.  These instructions
     are generated by default on POWER systems, anod not generated on
     PowerPC systems.  Do not use `-mstring' on little endian PowerPC
     systems, since those instructions do not work when the processor
     is in little endian mode.

`-mno-bit-align'
`-mbit-align'
     On System V.4 and embedded PowerPC systems do not (do) force
     structures and unions that contain bit fields to be aligned to the
     base type of the bit field.

     For example, by default a structure containing nothing but 8
     `unsigned' bitfields of length 1 would be aligned to a 4 byte
     boundary and have a size of 4 bytes.  By using `-mno-bit-align',
     the structure would be aligned to a 1 byte boundary and be one
     byte in size.

`-mno-strict-align'
`-mstrict-align'
     On System V.4 and embedded PowerPC systems do not (do) assume that
     unaligned memory references will be handled by the system.

`-mrelocatable'
`-mno-relocatable'
     On embedded PowerPC systems generate code that allows (does not
     allow) the program to be relocated to a different address at
     runtime.

`-mno-toc'
`-mtoc'
     On System V.4 and embedded PowerPC systems do not (do) assume that
     register 2 contains a pointer to a global area pointing to the
     addresses used in the program.

`-mno-traceback'
`-mtraceback'
     On embedded PowerPC systems do not (do) generate a traceback tag
     before the start of the function.  This tag can be used by the
     debugger to identify where the start of a function is.

`-mlittle'
`-mlittle-endian'
     On System V.4 and embedded PowerPC systems compile code for the
     processor in little endian mode.  The `-mlittle-endian' option is
     the same as `-mlittle'.

`-mbig'
`-mbig-endian'
     On System V.4 and embedded PowerPC systems compile code for the
     processor in big endian mode.  The `-mbig-endian' option is the
     same as `-mbig'.

`-mcall-sysv'
     On System V.4 and embedded PowerPC systems compile code using
     calling conventions that adheres to the March 1995 draft of the
     System V Application Binary Interface, PowerPC processor
     supplement.  This is the default unless you configured GPC using
     `powerpc-*-eabiaix'.

`-mcall-aix'
     On System V.4 and embedded PowerPC systems compile code using
     calling conventions that are similar to those used on AIX.  This
     is the default if you configured GPC using `powerpc-*-eabiaix'.

`-mprototype'
`-mno-prototype'
     On System V.4 and embedded PowerPC systems assume that all calls to
     variable argument functions are properly prototyped.  Otherwise,
     the compiler must insert an instruction before every non
     prototyped call to set or clear bit 6 of the condition code
     register (CR) to indicate whether floating point values were
     passed in the floating point registers in case the function takes
     a variable arguments.  With `-mprototype', only calls to
     prototyped variable argument functions will set or clear the bit.


File: ^.!gcc.docs.pascal.gpc,  Node: RT Options,  Next: MIPS Options,  Prev: RS/6000 and PowerPC Options,  Up: Submodel Options

IBM RT Options
--------------

   These `-m' options are defined for the IBM RT PC:

`-min-line-mul'
     Use an in-line code sequence for integer multiplies.  This is the
     default.

`-mcall-lib-mul'
     Call `lmul$$' for integer multiples.

`-mfull-fp-blocks'
     Generate full-size floating point data blocks, including the
     minimum amount of scratch space recommended by IBM.  This is the
     default.

`-mminimum-fp-blocks'
     Do not include extra scratch space in floating point data blocks.
     This results in smaller code, but slower execution, since scratch
     space must be allocated dynamically.

`-mfp-arg-in-fpregs'
     Use a calling sequence incompatible with the IBM calling
     convention in which floating point arguments are passed in
     floating point registers.  Note that `varargs.h' and `stdargs.h'
     will not work with floating point operands if this option is
     specified.

`-mfp-arg-in-gregs'
     Use the normal calling convention for floating point arguments.
     This is the default.

`-mhc-struct-return'
     Return structures of more than one word in memory, rather than in a
     register.  This provides compatibility with the MetaWare HighC (hc)
     compiler.  Use the option `-fpcc-struct-return' for compatibility
     with the Portable C Compiler (pcc).

`-mnohc-struct-return'
     Return some structures of more than one word in registers, when
     convenient.  This is the default.  For compatibility with the
     IBM-supplied compilers, use the option `-fpcc-struct-return' or the
     option `-mhc-struct-return'.


File: ^.!gcc.docs.pascal.gpc,  Node: MIPS Options,  Next: i386 Options,  Prev: RT Options,  Up: Submodel Options

MIPS Options
------------

   These `-m' options are defined for the MIPS family of computers:

`-mcpu=CPU TYPE'
     Assume the defaults for the machine type CPU TYPE when scheduling
     instructions.  The choices for CPU TYPE are `r2000', `r3000',
     `r4000', `r4400', `r4600', and `r6000'.  While picking a specific
     CPU TYPE will schedule things appropriately for that particular
     chip, the compiler will not generate any code that does not meet
     level 1 of the MIPS ISA (instruction set architecture) without the
     `-mips2' or `-mips3' switches being used.

`-mips1'
     Issue instructions from level 1 of the MIPS ISA.  This is the
     default.  `r3000' is the default CPU TYPE at this ISA level.

`-mips2'
     Issue instructions from level 2 of the MIPS ISA (branch likely,
     square root instructions).  `r6000' is the default CPU TYPE at this
     ISA level.

`-mips3'
     Issue instructions from level 3 of the MIPS ISA (64 bit
     instructions).  `r4000' is the default CPU TYPE at this ISA level.
     This option does not change the sizes of any of the Pascal data
     types.

`-mfp32'
     Assume that 32 32-bit floating point registers are available.
     This is the default.

`-mfp64'
     Assume that 32 64-bit floating point registers are available.
     This is the default when the `-mips3' option is used.

`-mgp32'
     Assume that 32 32-bit general purpose registers are available.
     This is the default.

`-mgp64'
     Assume that 32 64-bit general purpose registers are available.
     This is the default when the `-mips3' option is used.

`-mint64'
     Types long, int, and pointer are 64 bits.  This works only if
     `-mips3' is also specified.

`-mlong64'
     Types long and pointer are 64 bits, and type int is 32 bits.  This
     works only if `-mips3' is also specified.

`-mmips-as'
     Generate code for the MIPS assembler, and invoke `mips-tfile' to
     add normal debug information.  This is the default for all
     platforms except for the OSF/1 reference platform, using the
     OSF/rose object format.  If the either of the `-gstabs' or
     `-gstabs+' switches are used, the `mips-tfile' program will
     encapsulate the stabs within MIPS ECOFF.

`-mgas'
     Generate code for the GNU assembler.  This is the default on the
     OSF/1 reference platform, using the OSF/rose object format.

`-mrnames'
`-mno-rnames'
     The `-mrnames' switch says to output code using the MIPS software
     names for the registers, instead of the hardware names (ie, A0
     instead of $4).  The only known assembler that supports this option
     is the Algorithmics assembler.

`-mgpopt'
`-mno-gpopt'
     The `-mgpopt' switch says to write all of the data declarations
     before the instructions in the text section, this allows the MIPS
     assembler to generate one word memory references instead of using
     two words for short global or static data items.  This is on by
     default if optimization is selected.

`-mstats'
`-mno-stats'
     For each non-inline function processed, the `-mstats' switch
     causes the compiler to emit one line to the standard error file to
     print statistics about the program (number of registers saved,
     stack size, etc.).

`-mmemcpy'
`-mno-memcpy'
     The `-mmemcpy' switch makes all block moves call the appropriate
     string function (`memcpy' or `bcopy') instead of possibly
     generating inline code.

`-mmips-tfile'
`-mno-mips-tfile'
     The `-mno-mips-tfile' switch causes the compiler not postprocess
     the object file with the `mips-tfile' program, after the MIPS
     assembler has generated it to add debug support.  If `mips-tfile'
     is not run, then no local variables will be available to the
     debugger.  In addition, `stage2' and `stage3' objects will have
     the temporary file names passed to the assembler embedded in the
     object file, which means the objects will not compare the same.
     The `-mno-mips-tfile' switch should only be used when there are
     bugs in the `mips-tfile' program that prevents compilation.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not part of GNU Pascal.
     Normally the facilities of the machine's usual C compiler are
     used, but this can't be done directly in cross-compilation.  You
     must make your own arrangements to provide suitable library
     functions for cross-compilation.

`-mhard-float'
     Generate output containing floating point instructions.  This is
     the default if you use the unmodified sources.

`-mabicalls'
`-mno-abicalls'
     Emit (or do not emit) the pseudo operations `.abicalls',
     `.cpload', and `.cprestore' that some System V.4 ports use for
     position independent code.

`-mlong-calls'
`-mno-long-calls'
     Do all calls with the `JALR' instruction, which requires loading
     up a function's address into a register before the call.  You need
     to use this switch, if you call outside of the current 512
     megabyte segment to functions that are not through pointers.

`-mhalf-pic'
`-mno-half-pic'
     Put pointers to extern references into the data section and load
     them up, rather than put the references in the text section.

`-membedded-pic'
`-mno-embedded-pic'
     Generate PIC code suitable for some embedded systems.  All calls
     are made using PC relative address, and all data is addressed
     using the $gp register.  This requires GNU as and GNU ld which do
     most of the work.

`-membedded-data'
`-mno-embedded-data'
     Allocate variables to the read-only data section first if
     possible, then next in the small data section if possible,
     otherwise in data.  This gives slightly slower code than the
     default, but reduces the amount of RAM required when executing,
     and thus may be preferred for some embedded systems.

`-msingle-float'
`-mdouble-float'
     The `-msingle-float' switch tells gcc to assume that the floating
     point coprocessor only supports single precision operations, as on
     the `r4650' chip.  The `-mdouble-float' switch permits gcc to use
     double precision operations.  This is the default.

`-mmad'
`-mno-mad'
     Permit use of the `mad', `madu' and `mul' instructions, as on the
     `r4650' chip.

`-m4650'
     Turns on `-msingle-float', `-mmad', and, at least for now,
     `-mcpu=r4650'.

`-EL'
     Compile code for the processor in little endian mode.  The
     requisite libraries are assumed to exist.

`-EB'
     Compile code for the processor in big endian mode.  The requisite
     libraries are assumed to exist.

`-G NUM'
     Put global and static items less than or equal to NUM bytes into
     the small data or bss sections instead of the normal data or bss
     section.  This allows the assembler to emit one word memory
     reference instructions based on the global pointer (GP or $28),
     instead of the normal two words used.  By default, NUM is 8 when
     the MIPS assembler is used, and 0 when the GNU assembler is used.
     The `-G NUM' switch is also passed to the assembler and linker.
     All modules should be compiled with the same `-G NUM' value.

`-nocpp'
     Tell the MIPS assembler to not run it's preprocessor over user
     assembler files (with a `.s' suffix) when assembling them.


File: ^.!gcc.docs.pascal.gpc,  Node: i386 Options,  Next: HPPA Options,  Prev: MIPS Options,  Up: Submodel Options

Intel 386 Options
-----------------

   These `-m' options are defined for the i386 family of computers:

`-m486'
`-m386'
     Control whether or not code is optimized for a 486 instead of an
     386.  Code generated for an 486 will run on a 386 and vice versa.

`-mieee-fp'
`-mno-ieee-fp'
     Control whether or not the compiler uses IEEE floating point
     comparisons.  These handle correctly the case where the result of a
     comparison is unordered.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not part of GNU Pascal.
     Normally the facilities of the machine's usual C compiler are
     used, but this can't be done directly in cross-compilation.  You
     must make your own arrangements to provide suitable library
     functions for cross-compilation.

     On machines where a function returns floating point results in the
     80387 register stack, some floating point opcodes may be emitted
     even if `-msoft-float' is used.

`-mno-fp-ret-in-387'
     Do not use the FPU registers for return values of functions.

     The usual calling convention has functions return values of types
     `float' and `double' in an FPU register, even if there is no FPU.
     The idea is that the operating system should emulate an FPU.

     The option `-mno-fp-ret-in-387' causes such values to be returned
     in ordinary CPU registers instead.

`-mno-fancy-math-387'
     Some 387 emulators do not support the `sin', `cos' and `sqrt'
     instructions for the 387.  Specify this option to avoid generating
     those instructions. This option is the default on FreeBSD.  As of
     revision 2.6.1, these instructions are not generated unless you
     also use the `-ffast-math' switch.

`-malign-double'
`-mno-align-double'
     Control whether GNU Pascal aligns `double', `long double', and
     `long long' variables on a two word boundary or a one word
     boundary.  Aligning `double' variables on a two word boundary will
     produce code that runs somewhat faster on a `Pentium' at the
     expense of more memory.

     *Warning:* if you use the `-malign-double' switch, structures
     containing the above types will be aligned differently than the
     published application binary interface specifications for the 386.

`-msvr3-shlib'
`-mno-svr3-shlib'
     Control whether GNU Pascal places uninitialized locals into `bss'
     or `data'.  `-msvr3-shlib' places these locals into `bss'.  These
     options are meaningful only on System V Release 3.

`-mno-wide-multiply'
`-mwide-multiply'
     Control whether GNU Pascal uses the `mul' and `imul' that produce
     64 bit results in `eax:edx' from 32 bit operands to do `long long'
     multiplies and 32-bit division by constants.

`-mrtd'
     Use a different function-calling convention, in which functions
     that take a fixed number of arguments return with the `ret' NUM
     instruction, which pops their arguments while returning.  This
     saves one instruction in the caller since there is no need to pop
     the arguments there.

     You can specify that an individual function is called with this
     calling sequence with the function attribute `stdcall'.  You can
     also override the `-mrtd' option by using the function attribute
     `cdecl'.

     *Warning:* this calling convention is incompatible with the one
     normally used on Unix, so you cannot use it if you need to call
     libraries compiled with the Unix compiler.

     Also, you must provide function prototypes for all functions that
     take variable numbers of arguments (including `printf'); otherwise
     incorrect code will be generated for calls to those functions.

     In addition, seriously incorrect code will result if you call a
     function with too many arguments.  (Normally, extra arguments are
     harmlessly ignored.)

`-mreg-alloc=REGS'
     Control the default allocation order of integer registers.  The
     string REGS is a series of letters specifying a register.  The
     supported letters are: `a' allocate EAX; `b' allocate EBX; `c'
     allocate ECX; `d' allocate EDX; `S' allocate ESI; `D' allocate
     EDI; `B' allocate EBP.

`-mregparm=NUM'
     Control how many registers are used to pass integer arguments.  By
     default, no registers are used to pass arguments, and at most 3
     registers can be used.  You can control this behavior for a
     specific function by using the function attribute `regparm'.

     *Warning:* if you use this switch, and NUM is nonzero, then you
     must build all modules with the same value, including any
     libraries.  This includes the system libraries and startup modules.

`-malign-loops=NUM'
     Align loops to a 2 raised to a NUM byte boundary.  If
     `-malign-loops' is not specified, the default is 2.

`-malign-jumps=NUM'
     Align instructions that are only jumped to to a 2 raised to a NUM
     byte boundary.  If `-malign-jumps' is not specified, the default is
     2 if optimizing for a 386, and 4 if optimizing for a 486.

`-malign-functions=NUM'
     Align the start of functions to a 2 raised to NUM byte boundary.
     If `-malign-jumps' is not specified, the default is 2 if optimizing
     for a 386, and 4 if optimizing for a 486.


File: ^.!gcc.docs.pascal.gpc,  Node: HPPA Options,  Next: Intel 960 Options,  Prev: i386 Options,  Up: Submodel Options

HPPA Options
------------

   These `-m' options are defined for the HPPA family of computers:

`-mpa-risc-1-0'
     Generate code for a PA 1.0 processor.

`-mpa-risc-1-1'
     Generate code for a PA 1.1 processor.

`-mjump-in-delay'
     Fill delay slots of function calls with unconditional jump
     instructions by modifying the return pointer for the function call
     to be the target of the conditional jump.

`-mmillicode-long-calls'
     Generate code which assumes millicode routines can not be reached
     by the standard millicode call sequence, linker-generated
     long-calls, or linker-modified millicode calls.  In practice this
     should only be needed for dynamicly linked executables with
     extremely large SHLIB_INFO sections.

`-mdisable-fpregs'
     Prevent floating point registers from being used in any manner.
     This is necessary for compiling kernels which perform lazy context
     switching of floating point registers.  If you use this option and
     attempt to perform floating point operations, the compiler will
     abort.

`-mdisable-indexing'
     Prevent the compiler from using indexing address modes.  This
     avoids some rather obscure problems when compiling MIG generated
     code under MACH.

`-mfast-indirect-calls'
     Generate code which performs faster indirect calls.  Such code is
     suitable for kernels and for static linking.  The fast indirect
     call code will fail miserably if it's part of a dynamically linked
     executable and in the presense of nested functions.

`-mportable-runtime'
     Use the portable calling conventions proposed by HP for ELF
     systems.

`-mgas'
     Enable the use of assembler directives only GAS understands.

`-mschedule=CPU TYPE'
     Schedule code according to the constraints for the machine type
     CPU TYPE.  The choices for CPU TYPE are `700' for 7N0 machines,
     `7100' for 7N5 machines, and `7100' for 7N2 machines.  `700' is
     the default for CPU TYPE.

     Note the `7100LC' scheduling information is incomplete and using
     `7100LC' often leads to bad schedules.  For now it's probably best
     to use `7100' instead of `7100LC' for the 7N2 machines.

`-msoft-float'
     Generate output containing library calls for floating point.
     *Warning:* the requisite libraries are not available for all HPPA
     targets.  Normally the facilities of the machine's usual C
     compiler are used, but this cannot be done directly in
     cross-compilation.  You must make your own arrangements to provide
     suitable library functions for cross-compilation.  The embedded
     target `hppa1.1-*-pro' does provide software floating point
     support.

     `-msoft-float' changes the calling convention in the output file;
     therefore, it is only useful if you compile *all* of a program with
     this option.  In particular, you need to compile `libgcc.a', the
     library that comes with GNU Pascal, with `-msoft-float' in order
     for this to work.


File: ^.!gcc.docs.pascal.gpc,  Node: Intel 960 Options,  Next: DEC Alpha Options,  Prev: HPPA Options,  Up: Submodel Options

Intel 960 Options
-----------------

   These `-m' options are defined for the Intel 960 implementations:

`-mCPU TYPE'
     Assume the defaults for the machine type CPU TYPE for some of the
     other options, including instruction scheduling, floating point
     support, and addressing modes.  The choices for CPU TYPE are `ka',
     `kb', `mc', `ca', `cf', `sa', and `sb'.  The default is `kb'.

`-mnumerics'
`-msoft-float'
     The `-mnumerics' option indicates that the processor does support
     floating-point instructions.  The `-msoft-float' option indicates
     that floating-point support should not be assumed.

`-mleaf-procedures'
`-mno-leaf-procedures'
     Do (or do not) attempt to alter leaf procedures to be callable
     with the `bal' instruction as well as `call'.  This will result in
     more efficient code for explicit calls when the `bal' instruction
     can be substituted by the assembler or linker, but less efficient
     code in other cases, such as calls via function pointers, or using
     a linker that doesn't support this optimization.

`-mtail-call'
`-mno-tail-call'
     Do (or do not) make additional attempts (beyond those of the
     machine-independent portions of the compiler) to optimize
     tail-recursive calls into branches.  You may not want to do this
     because the detection of cases where this is not valid is not
     totally complete.  The default is `-mno-tail-call'.

`-mcomplex-addr'
`-mno-complex-addr'
     Assume (or do not assume) that the use of a complex addressing
     mode is a win on this implementation of the i960.  Complex
     addressing modes may not be worthwhile on the K-series, but they
     definitely are on the C-series.  The default is currently
     `-mcomplex-addr' for all processors except the CB and CC.

`-mcode-align'
`-mno-code-align'
     Align code to 8-byte boundaries for faster fetching (or don't
     bother).  Currently turned on by default for C-series
     implementations only.

`-mic-compat'
`-mic2.0-compat'
`-mic3.0-compat'
     Enable compatibility with iC960 v2.0 or v3.0.

`-masm-compat'
`-mintel-asm'
     Enable compatibility with the iC960 assembler.

`-mstrict-align'
`-mno-strict-align'
     Do not permit (do permit) unaligned accesses.

`-mold-align'
     Enable structure-alignment compatibility with Intel's gcc release
     version 1.3 (based on gcc 1.37).  Currently this is buggy in that
     `#pragma align 1' is always assumed as well, and cannot be turned
     off.


File: ^.!gcc.docs.pascal.gpc,  Node: DEC Alpha Options,  Next: Clipper Options,  Prev: Intel 960 Options,  Up: Submodel Options

DEC Alpha Options
-----------------

   These `-m' options are defined for the DEC Alpha implementations:

`-mno-soft-float'
`-msoft-float'
     Use (do not use) the hardware floating-point instructions for
     floating-point operations.  When `-msoft-float' is specified,
     functions in `libgcc1.c' will be used to perform floating-point
     operations.  Unless they are replaced by routines that emulate the
     floating-point operations, or compiled in such a way as to call
     such emulations routines, these routines will issue floating-point
     operations.   If you are compiling for an Alpha without
     floating-point operations, you must ensure that the library is
     built so as not to call them.

     Note that Alpha implementations without floating-point operations
     are required to have floating-point registers.

`-mfp-reg'
`-mno-fp-regs'
     Generate code that uses (does not use) the floating-point register
     set.  `-mno-fp-regs' implies `-msoft-float'.  If the floating-point
     register set is not used, floating point operands are passed in
     integer registers as if they were integers and floating-point
     results are passed in $0 instead of $f0.  This is a non-standard
     calling sequence, so any function with a floating-point argument
     or return value called by code compiled with `-mno-fp-regs' must
     also be compiled with that option.

     A typical use of this option is building a kernel that does not
     use, and hence need not save and restore, any floating-point
     registers.


File: ^.!gcc.docs.pascal.gpc,  Node: Clipper Options,  Next: H8/300 Options,  Prev: DEC Alpha Options,  Up: Submodel Options

Clipper Options
---------------

   These `-m' options are defined for the Clipper implementations:

`-mc300'
     Produce code for a C300 Clipper processor. This is the default.

`-mc400'
     Produce code for a C400 Clipper processor i.e. use floating point
     registers f8..f15.


File: ^.!gcc.docs.pascal.gpc,  Node: H8/300 Options,  Next: System V Options,  Prev: Clipper Options,  Up: Submodel Options

H8/300 Options
--------------

   These `-m' options are defined for the H8/300 implementations:

`-mrelax'
     Shorten some address references at link time, when possible; uses
     the linker option `-relax'.  *Note `ld' and the H8/300:
     (ld.info)H8/300, for a fuller description.

`-mh'
     Generate code for the H8/300H.


File: ^.!gcc.docs.pascal.gpc,  Node: System V Options,  Prev: H8/300 Options,  Up: Submodel Options

Options for System V
--------------------

   These additional options are available on System V Release 4 for
compatibility with other compilers on those systems:

`-Qy'
     Identify the versions of each tool used by the compiler, in a
     `.ident' assembler directive in the output.

`-Qn'
     Refrain from adding `.ident' directives to the output file (this is
     the default).

`-YP,DIRS'
     Search the directories DIRS, and no others, for libraries
     specified with `-l'.

`-Ym,DIR'
     Look in the directory DIR to find the M4 preprocessor.  The
     assembler uses this option.


File: ^.!gcc.docs.pascal.gpc,  Node: Environment Variables,  Prev: Submodel Options,  Up: Invoking GPC

Environment Variables Affecting GNU Pascal
==========================================

   This section describes several environment variables that affect how
GNU CC operates.  They work by specifying directories or prefixes to use
when searching for various kinds of files.

   Note that you can also specify places to search using options such as
`-B', `-I' and `-L' (*note Directory Options::.).  These take
precedence over places specified using environment variables, which in
turn take precedence over those specified by the configuration of GNU
CC.

`TMPDIR'
     If `TMPDIR' is set, it specifies the directory to use for temporary
     files.  GNU Pascal uses temporary files to hold the output of one
     stage of compilation which is to be used as input to the next
     stage: for example, the output of the preprocessor, which is the
     input to the compiler proper.

`GPC_EXEC_PREFIX'
     If `GPC_EXEC_PREFIX' is set, it specifies a prefix to use in the
     names of the subprograms executed by the compiler.  No slash is
     added when this prefix is combined with the name of a subprogram,
     but you can specify a prefix that ends with a slash if you wish.

     If GNU Pascal cannot find the subprogram using the specified
     prefix, it tries looking in the usual places for the subprogram.

     The default value of `GPC_EXEC_PREFIX' is `PREFIX/lib/gcc-lib/'
     where PREFIX is the value of `prefix' when you ran the `configure'
     script.

     Other prefixes specified with `-B' take precedence over this
     prefix.

     This prefix is also used for finding files such as `crt0.o' that
     are used for linking.

     In addition, the prefix is used in an unusual way in finding the
     directories to search for header files.  For each of the standard
     directories whose name normally begins with
     `/usr/local/lib/gcc-lib' (more precisely, with the value of
     `GPC_INCLUDE_DIR'), GNU Pascal tries replacing that beginning with
     the specified prefix to produce an alternate directory name.
     Thus, with `-Bfoo/', GNU Pascal will search `foo/bar' where it
     would normally search `/usr/local/lib/bar'.  These alternate
     directories are searched first; the standard directories come next.

`COMPILER_PATH'
     The value of `COMPILER_PATH' is a colon-separated list of
     directories, much like `PATH'.  GNU Pascal tries the directories
     thus specified when searching for subprograms, if it can't find the
     subprograms using `GPC_EXEC_PREFIX'.

`LIBRARY_PATH'
     The value of `LIBRARY_PATH' is a colon-separated list of
     directories, much like `PATH'.  When configured as a native
     compiler, GNU Pascal tries the directories thus specified when
     searching for special linker files, if it can't find them using
     `GPC_EXEC_PREFIX'.  Linking using GNU Pascal also uses these
     directories when searching for ordinary libraries for the `-l'
     option (but directories specified with `-L' come first).

`C_INCLUDE_PATH'
`CPLUS_INCLUDE_PATH'
`OBJC_INCLUDE_PATH'
     These environment variables pertain to particular languages.  Each
     variable's value is a colon-separated list of directories, much
     like `PATH'.  When GNU Pascal searches for header files, it tries
     the directories listed in the variable for the language you are
     using, after the directories specified with `-I' but before the
     standard header file directories.

`DEPENDENCIES_OUTPUT'
     If this variable is set, its value specifies how to output
     dependencies for Make based on the header files processed by the
     compiler.  This output looks much like the output from the `-M'
     option (*note Preprocessor Options::.), but it goes to a separate
     file, and is in addition to the usual results of compilation.

     The value of `DEPENDENCIES_OUTPUT' can be just a file name, in
     which case the Make rules are written to that file, guessing the
     target name from the source file name.  Or the value can have the
     form `FILE TARGET', in which case the rules are written to file
     FILE using TARGET as the target name.


File: ^.!gcc.docs.pascal.gpc,  Node: Keywords,  Next: Built-in,  Prev: Invoking GPC,  Up: Top

Keywords and operators supported by GNU Pascal
**********************************************

   This chapter lists all keywords and operators understood by GNU
Pascal.

Keywords
========

   By default, keywords can be redefined to make it possible that every
correct ISO 7185 program can be compiled.  However, you can use the
compiler switches `--pascal-standard', `--pascal-extended',
`--pascal-object', `--pascal-borland', and `--pascal-sc' to tell GPC
that keywords of a given standard must not to be redefined.

   The keywords are taken from the following standards:

   * ISO 7185 Standard Pascal (SP)

   * ISO 10206 Extended Pascal (EP)

   * ANSI draft Object Pascal (OP) *(not yet implemented)*

   * Borland Pascal 7.0 (BP)

   * Pascal-SC (PXSC, Pascal eXtensions for Scientific Calculations)

     Keyword         Pascal standard        Remarks
     --------------------------------------------------------------------------
     Absolute        Borland                overload variables
     Abstract        Object                 not implemented
     All             GNU                    EP "export foo = all" extension
     And             ISO Standard
     And_then        ISO Extended           short-circuit Boolean AND operator
     Array           ISO Standard
     Asm             Borland, GNU           GNU-style assembler
     Begin           ISO Standard
     Bindable        ISO Extended           external binding of files, etc.
     Case            ISO Standard
     Class           Object                 not implemented
     Const           ISO Standard
     Constructor     Object, Borland        only BP version implemented
     Destructor      Object, Borland        only BP version implemented
     Div             ISO Standard
     Do              ISO Standard
     Downto          ISO Standard
     Else            ISO Standard
     End             ISO Standard
     Export          ISO Extended           Module Interface export
     File            ISO Standard
     For             ISO Standard
     Function        ISO Standard
     Goto            ISO Standard
     If              ISO Standard
     Import          ISO Extended           Module Interface import
     Implementation  ISO Extended, Borland  Module (EP) or Unit (BP) Impl. part
     Inherited       Object, Borland        only BP version implemented
     In              ISO Standard
     Inline          Borland, GNU           only GNU inline functions implem.
     Interface       ISO Extended, Borland  Module (EP) or Unit (BP) Int. part
     Is              Object                 not implemented
     Label           ISO Standard
     Mod             ISO Standard
     Module          ISO Extended, PXSC     PXSC version only partially implem.
     Nil             ISO Standard
     Not             ISO Standard
     Object          Borland                BP 7.0 style class definition
     Of              ISO Standard
     Only            ISO Extended           import specification
     Operator        PXSC                   operator definition
     Or              ISO Standard
     Or_else         ISO Extended           short-circuit Boolean OR operator
     Otherwise       ISO Extended           default case label
     Packed          ISO Standard           does not yet pack
     Pow             ISO Extended           exponentiation op. (integer expon.)
     Procedure       ISO Standard
     Program         ISO Standard
     Property        Object                 not implemented
     Protected       ISO Extended           read-only formal parameters
     Qualified       ISO Extended           import specification
     Record          ISO Standard
     Repeat          ISO Standard
     Restricted      ISO Extended           type specification
     Set             ISO Standard
     Shl             Borland                left bit-shift operator
     Shr             Borland                right bit-shift operator
     Then            ISO Standard
     To              ISO Standard
     Type            ISO Standard
     Unit            Borland                Borland (or UCSD) style Modules
     Until           ISO Standard
     Uses            Borland                Borland (or UCSD) style import
     Value           ISO Extended           variable initializer
     Var             ISO Standard
     View            Object                 not implemented
     Virtual         Borland, Object        only Borland version implemented
     While           ISO Standard
     With            ISO Standard
     Xor             Borland                Boolean/bitwise exclusive OR op.

Operators
=========

   GNU Pascal operators, ordered by precedence.

   The PXSC operators `+<', `-<', etc. are not implemented into GNU
Pascal but may be defined by the user.  If you do so and meet the PXSC
requirements, please let us know.  The other real operators do *not*
meet PXSC requirements.

   The Object Pascal operator `IS' is not implemented.

     :=
     <    =    >    IN   <>   >=   <=
     +    -    OR   +<   -<   +>   ->
     *    /    DIV  MOD  AND  SHL  SHR  XOR  *<   /<   *>   />
     POW  **   IS
     NOT


File: ^.!gcc.docs.pascal.gpc,  Node: Built-in,  Next: Extensions,  Prev: Keywords,  Up: Top

Redefineable built-in identifiers
*********************************

   The following identifiers are built in into GNU Pascal but may be
redefined according to any supported Pascal standard.

     Maxint
     False
     True
     Input
     Output

     Rewrite
     Reset
     Put
     Get
     Write
     Read
     Writeln
     Readln
     Page
     New
     Dispose
     Abs
     Sqr
     Sin
     Cos
     Exp
     Ln
     Sqrt
     Arctan
     Trunc
     Round
     Pack
     Unpack
     Ord
     Chr
     Succ
     Pred
     Odd
     Eof
     Eoln

   Directives

     Asmname            Specify case-sensitive external name for Function
     C                  External name for Function shall be lowercase
     C_language         same as C
     Forward
     External           External Name of Function Has First Letter Uppercase
     Extern             same as External

   Extended Pascal required module interfaces

     Standardoutput
     Standardinput

   Object Pascal directive (not implemented)

     Override

   Extended Pascal required words

     Maxchar
     Maxreal
     Minreal
     Epsreal

   Extended Pascal required Procedures and Functions

     Gettimestamp
     Date
     Time
     Halt
     Extend
     Seekwrite
     Seekread
     Seekupdate
     Empty
     Update
     Position
     Lastposition
     Re
     Im
     Cmplx
     Card
     Arg

   Extended Pascal external binding

     Bind
     Unbind
     Binding

   Extended Pascal complex type functions

     Polar

   Extended Pascal String functions

     Readstr            Read from a string rather than a file
     Writestr           Write to a string rather than a file
     Length
     Index              Search in a string
     Substr             also `MyStr [ 1..5 ]'
     Trim
     Eq                 lexical string comparision
     Lt
     Gt
     Ne
     Le
     Ge

   Extended pascal required string schema type generator

     String

   Object pascal (not implemented)

     Copy
     Null
     Root
     Textwritable
     Self

   Borland Pascal

     GetMem             Allocate memory with given size in bytes
     FreeMem            Free memory allocated with GetMem
     Inc                Increment
     Dec                Decrement

   More exotic fruits and birds (GPC extensions)

     Static             C-sense storage class specifications
     __const__
     __external__
     __inline__
     __static__
     __volatile__
     __byte__           C-style type size modifiers
     __short__
     __long__
     __longlong__
     __unsigned__

     Asm                Inline assembly (GNU style)
     Alignof
     Break              C-style
     Continue
     Return
     Sizeof
     Max                for enumeral and real types
     Min

     Conjugate
     Mark
     Release

     Default            like `otherwise' in a `case' statement
     Others

     Close
     Definesize

   Standard Pascal data types

     Integer
     Real
     Boolean
     Char
     Text

   Extended Pascal complex type

     Complex

   GPC extensions: void type (two spellings)

     __void__
     Void

   GPC extension: C compatibility string type

     __cstring__

   Extended Pascal: TimeStamp and BindingType

     Timestamp
     Bindingtype


File: ^.!gcc.docs.pascal.gpc,  Node: Extensions,  Next: Extended Pascal,  Prev: Built-in,  Up: Top

GNU Pascal extensions
*********************

Extensions to ISO-7185 Pascal language
======================================

   GPC contains a number of extensions to the ISO 7185 Pascal language.

   Most of these extensions are written so that they should conform
conform to the international standard ISO/IEC 10206 : 1991, Information
technology - Programming Languages - Extended Pascal.

   GPC is not yet fully compliant to the requirements of the Extended
Pascal language.

   The following Extended Pascal features are implemented:
   * I/O from/to strings

   * append file open mode: `extend(File)'

   * binding of external objects (GPC supports only binding of files)

   * complex dyadic operations `+,-,/,*' and monadic `-,+'

   * complex exponentiation operators (`POW' and `**')

   * complex functions (`sqr,arctan,sqrt,exp,ln,sin,cos')

   * complex number info with `re, im' and `arg' functions

   * complex numbers constructed by `cmplx' or `polar'

   * constant expressions

   * direct access I/O

   * exponentiation operators (`POW' and `**')

   * function result variable

   * functions returning structured types

   * generalized `Succ/Pred' (`val := succ (val, 5);')

   * `gettimestamp, date, time'

   * `halt' procedure

   * initial values to type declarations and/or variable declarations

   * local variable declarations may dynamically select the type and
     size

   * `maxchar/minreal/maxreal/epsreal' values.

   * modules are partially supported (@@incomplete, see below)

   * non-decimal numbers, base from 2 through 36: `base#number'

   * pointer and component access of structured return values

   * protected parameters

   * ranges and otherwise in case statements and variant records

   * read procedure can read strings from text files

   * relaxation of rules on number & order of declarations

   * required module interfaces `StandardInput' and `StandardOutput'

   * restricted types

   * set extensions (symmetric difference(`XOR') and `CARD')

   * short circuit logical operators (`AND_THEN, OR_ELSE')

   * standard numeric input (ISO 6093)

   * string and char values are compatible

   * string catenations with "`+'"

   * string comparisons with and without padding

   * string functions (`trim,substr,index,length')

   * string schema (variable length strings)

   * string schema discriminant 'Capacity' dynamically set with NEW

   * substring variables (`str[5..7] := 'foo';')

   * type inquiry

   * underscore in identifiers

   * zero fieldwidth output

   Gpc extensions *not* in Extended Pascal:
   * alphanumeric labels

   * assembler code inclusion with access to variables

   * character escapes in strings

   * close file (@@ `unbind(F)' also closes a bound file `F')

   * computed goto

   * function pointers

   * `halt' procedure may have a numeric exit status parameter

   * `mark/release'

   * optional file name in `reset/rewrite/extend' as a string

   * `return / break / continue' statements

   * simple "modules" in addition to the Extended Pascal modules.

   * `sizeof/alignof' functions

   * `string[ XX ]' works like `string(XX)' as a string schema type
     selector

   * storage qualifiers in variable declarations

   * synonyms for `otherwise': `others' and `default'

   * taking address of labels

   * taking address of objects

   * type casts

   * type qualifiers

   * module initializers can be run in user specified order

   * source file preprosessor

Extended Pascal features still missing from GPC
-----------------------------------------------

   * set member iteration (`FOR ch IN [ 'a'..'z','0'..'9' ] DO...')

   * set types with variable bounds

   * structured value constructors

   * general schema types & make `NEW' work with them

   * some features of the module interface missing

   * subrange lower bound as an expression   (this is *hard* to do with
     an LALR(1) parser in single pass!     GPC allows upper bound as an
     arbitrary expression;    lower bound must now be an identifier, a
     constant or a    variable name.)

I/O to text files:
------------------

   GPC implements "lazy" text file I/O, i.e. do a `PUT' as soon as you
can and do `GET' as late as you can.

   This should avoid most of the problems sometimes considered to be
the most stupid feature of Pascal.

   When passing a file buffer as parameter the buffer is validated when
the parameter is passed.  @@ Perhaps it would be nice to hack it to be
validated when the VAR parameter is referenced...

   When any lazy file is `RESET', the file buffer state is set to
undefined. It is validated on the first reference to it.  Now this is
also true for terminal devices.

Variable length strings in GPC:
-------------------------------

   Extended Pascal has a "type selector" feature called schema types.

   GPC does not yet implement general schema types, but the `STRING
SCHEMA' is now implemented.

   (An example of a (unimplemented) schemata would be, e.g:

     Matrix (N,M: Positive_int) = array [ 1..N, 1..M ] of integer;

   Here the `M' and `N' are discriminant identifiers.)

   A `STRING SCHEMA' is the only predefined schema type in Extended
Pascal, with one required discriminant identifier "`Capacity'".

   The string schema type, if explicitely defined, could look like:

     TYPE string(capacity) = packed array [ 1..capacity ] of char;

   Internally GPC implements `STRING SCHEMA' as follows:

   The type representing the `SCHEMA TYPE' is a `RECORD_TYPE' node,
with the following fields:

     STRING  = RECORD
         Capacity : integer;
         length   : integer;
         string   : packed array [ 1..Capacity ] of char;
       END;

   The "`Capacity'" field may be directly referenced by user,

   "`length'" is referenced by a predefined string function
`LENGTH(str)' and contains the current string length.

   "`string'" contains the chars in the string.

   The "`string'" and "`length'" fields can not be directly referenced
by a user program.

   References to the schema discriminants are allowed, and the `WITH'
statement is also allowed, so one can say:

     var str : string (80);
     begin
        writeln (str.capacity),         (* writes 80 *)

        with str do
          writeln (capacity);           (* writes 80 *)
     end;

   When a new `SCHEMA_TYPE' is created, the discriminant identifier
fields need to be initialized. GPC initializes the new schema type
discriminant identifiers of every `VAR_DECL' node before it executes
any instructions of the procedure, function or program where the string
variable is declared.

   If new internal schema types are created (for conversion of
fixed-string or char type parameters to a string schema formal
parameter), the discriminant identifiers are initialized immediately.
The discriminant identifiers of `PARM_DECL' nodes are not initialized
separately, they get their values from the actual parameters.

   If a parameter is a `SCHEMA_NAME' (a schema with no discriminant
identifiers), a proto string schema is used as the type of the
parameter.

   * VAR-parameter: An actual parameter to a formal schema name must be
     of `STRING_SCHEMA' type. The type of the actual parameter is used
     instead of the proto schema for the formal parameter.

   * VALUE-parameter: An actual parameter to a schema name may be
     either a `STRING_SCHEMA' type, a fixed string type or a char type.
     If the actual parameter is a string schema type, that is used
     instead of the proto schema. If it is not a schema, a new variable
     length string `VAR_DECL' is created, the actual parameter is
     copied to the new variable and the "`capacity'" field is set to
     the length of the actual variable.

   Variable length string parameters look like:

     PROGRAM Zap (output);

     TYPE
        stype = string (10);
        sptr  = ^string;

     VAR
        str  : stype;
        str2 : string(100000);
        dstr : ^string;
        zstr : sptr;
        len  : integer value 256;

       (* "string" accepts any length of strings *)
       PROCEDURE foo(z: string);

       BEGIN
         writeln ('Capacity : ',z.capacity);
         writeln ('Length   : ',length (z));
         writeln ('Contents : ',z);
       END;

       (* Another way to use dynamic strings *)
       PROCEDURE bar(slen : integer);

       var
         lstring : string (slen);
         foostr  : type of lstring;

       BEGIN
         lstring := 'Hello World!';
         foo (lstring);
         foostr := 'Ent{ miksi juuri t{m{?';
         foo(foostr);
       END;

     BEGIN
       str   := 'KUKKUU';
       str2  := 'A longer string variable';

       new (dstr, 1000);     { Select the string Capacity with NEW }
       dstr^ := 'The max length of this is 1000 chars';
       new (zstr, len);
       zstr^ := 'This should fit here';

       foo(str);
       foo(str2);
       foo('This is a constant string');
       foo('R');             { A char parameter to string routine }
       foo('');              { An empty string }
       foo (dstr^);
       foo (zstr^);
       bar (10000);
     END. (* Zap *)

   In the above example, the required procedure `NEW' was used to
select the capacity of the strings. Procedure "`BAR'" also has a string
whose size depends of the parameter passed to it and another string
whose type will be the same than the type of the first string ("`type
of'" construct).

   All string and char types are compatible as long as the destination
string is long enough to hold the source in assignments. If the source
string is shorter than the destination, the destination is
automatically blank padded if the destination string is not of string
schema type.

String routine (mostly in library):
-----------------------------------

   `S1' and `S2' may be of string or char type.  `S' is of string type.

`WRITESTR (s, write-parameter-list)'
`READSTR (s, read-parameter-list)'
     Write to a string and read from a string.  The parameter lists are
     identical to write/read from `TEXT' files. The semantics is
     closely modeled after file I/O.

`INDEX(s1,s2)'
     If `S2' is empty, return 1 else if `S1' is empty return 0 else
     returns the position of `s2' in `s1' (an integer).

`LENGTH (s1)'
     Return the length of `S1' (an integer from `0..Capacity')

`TRIM (s1)'
     Returns a new string with spaces stripped of the end of `S'.

`SUBSTR (s1, i)'
`SUBSTR (s1, i, j)'
     If `J' is missing it is calculated as: `J := LENGTH (S1) - I + 1;'
     Return a new substring of `S1' that contains `J' characters
     starting from `I'.

`EQ (s1,s2)'
`NE (s1,s2)'
`LT (s1,s2)'
`LE (s1,s2)'
`GT (s1,s2)'
`GE (s1,s2)'
     Lexicographic comparisons of `S1' and `S2'. Returns boolean result.
     Strings are not padded with spaces.

`s1  = s2'
`s1 <> s2'
`s1  < s2'
`s1 <= s2'
`s1  > s2'
`s1 >= s2'
     Pascal string compare of `S1' and `S2'. Returns boolean result.
     Shorter string is blank padded to length of the longer one.

No name space pollution with extensions:
----------------------------------------

   In GPC you are free to re-define everything that is not a reserved
word in ISO 7185 Pascal in your program.

   All Extended Pascal additional "reserved words" may be redefined, so
you do not have to modify your code for GPC if you have an identifier
like `RESTRICTED' or `VALUE' or some such.  @@ This violates Extended
Pascal standard.

   You may also redefine words like `INTEGER' and `CHAR' if you like.

   @@ NOTE: The *only* exception to the redefinition rule currently is
the word `INLINE' (to make routines inline compiled), because I added
it in front of `PROCEDURE' or `FUNCTION'.  But I think I will change
the syntax later and make `INLINE' a directive instead of a reserved
word.

Compile time switches:
----------------------

   to get info of possible clashes of keywords and other info of your
program constructs that gpc thinks are "non-standard" use the switch
"`-pedantic'" when compiling. See the GCC info files.

   @@ I have not tested the switches like -Wall very much. If you do,
@@ give me info of error messages that don't make sense in Pascal.

   @@ As a rule, GPC implements most of the switches GCC implements,
and a couple of more that can not currently be set.

Implemented directives:
-----------------------

`FORWARD'
     Required by pascal standard.

`EXTERNAL'
     External routine which starts with a capital letter. (e.g. calling
     external function "`foo()'" will actually call "`Foo()'")

`EXTERN'
     Same as external

`C'
     Calls external routine "`foo()'" as "`foo()'" (no capitalization
     of the first letter)

`C_LANGUAGE'
     Same as C.

`STATIC'
     Make a function static in C sense.

     PROGRAM foo;

     PROCEDURE gotoxy(x,y: Integer); C;

     BEGIN
       gotoxy(10,10); (* Call external routine "gotoxy" *)
     END.

Set operations:
---------------

   GPC supports standard Pascal set operations. In addition it supports
the extended Pascal set operation symmetric difference (`set1 >< set2')
operation (a `XOR' of the set elements).

   It also has a function that counts the elements in the set: `a :=
card (set1)'

   *NOTE*: the set operations are still under construction, e.g. the set
code does not fully work in the 64 bit Alpha machines.

Initial values to type denoters:
--------------------------------

   A type (or variable) may be initialized to a value of expression
when it is declared, as in:

     program zap;

     type
        int10   = integer value 10;
        footype = real;
        mytype  = char value pred('A');
        etype   = (a,b,c,d,e,f,g) value d;

     var
        ii  : int10;                     (* Value of ii set to 10 *)
        ch  : mytype  value pred('z');
        aa  : integer value ii+10;
        foo : footype value sqrt(aa);
        e1  : etype;                     (* value set to d *)
        e2  : etype value g;             (* value set to g *)

     begin
     end.

   Extended pascal requires the type initializers to be constant
expressions. GPC allows any valid expression.

   Note, however, that the expressions that affect the size of storage
allocated for objects (e.g. the length of arrays) may contain variables
only inside functions or procedures.

   GPC evaluates the initial values used for the type when an
identifier is declared for that type.  If a variable is declared with a
type-denoter that uses a type-name which already has an initial value
the latter initialization has precedence.

   @@ GPC does not know how to calculate constant values for math
functions in the runtime library at compile time, e.g.
`exp(sin(2.4567))', so you should not use these kind of expressions in
object size expressions. (Extended Pascal allows this).

Date and time routines:
-----------------------

   Predefined date and time routines:

`procedure gettimestamp(VAR t: Timestamp);'
`function date(t: Timestamp) : packed array [ 1..DATE_LENGTH ] of char;'
`function time(t: Timestamp) : packed array [ 1..TIME_LENGTH ] of char;'
   `DATE_LENGTH' and `TIME_LENGTH' are implementation dependent
constants. See E.20 and E.22 in chapter IMPLEMENTATION DEPENDENT
FEATURES to find out these values for GPC.

   `GetTimeStamp(t)' fills the record T with values. If they are valid,
the boolean flags are set to TRUE.

   `TimeStamp' is a required predefined type in extended pascal
standard.  (It may be extended in an implementation.)

   The required part of the type looks like:
     TimeStamp = PACKED RECORD
                  DateValid,
                  TimeValid : Boolean;
                  year      : integer;
                  month     : 1 .. 12;
                  day       : 1 .. 31;
                  hour      : 0 .. 23;
                  minute    : 0 .. 59;
                  second    : 0 .. 59;
                END;

   @@ NOTE: `TimeStamp' may be later extended in GPC to contain the
following fields at the end of the `TimeStamp' record:

     Dst_used   : Boolean;     (* If daylight savings are used *)
     TimeZone   : Integer;     (* Positive if WEST, in minutes *)
     Weekday    : 0..6;        (* 0 is Sunday *)
     TimerValid : Boolean;     (* Is the following timer valid *)
     us_Timer   : Integer;     (* A microsecond timer that is a 32 bit
                                  modulus of the timer returned by the
                                  system. *)

   Fields `Dst_used, TimeZone' and `WeekDay' will be valid when
`DateValid' is `TRUE'. Field `us_Timer' will be valid when `TimerValid'
is `TRUE'.

Complex type and operations:
----------------------------

   The following sample programs illustrates most of the `COMPLEX' type
operations. In addition monadic `+' and `-' are supported and dyadic
`+,-,*,/' operations.

     program complex_test(output);

     var
        z1,z2       : complex;
        len, angle  : real;

     begin
        z1 := cmplx (2,1);
        writeln;
        writeln ('Complex number Z1 is: (',re(z1):1,',',im(z1):1,')');
        writeln;

        z2 := conjugate(z1); { GPC extension }
        writeln ('Conjugate of Z1 is: (',re(z2):1,',',im(z2):1,')');
        writeln;
        len   := abs (z1);
        angle := arg (z1);
        writeln ('The polar representation of Z1 is LENGTH=',len:1,
                 ' ANGLE=',angle:1);
        writeln;

        z2    := polar (len, angle);
        writeln ('Converting (LENGTH,ANGLE) back to (X,Y) gives: (',
                  re(z2):1,',',im(z2):1,')');
        writeln;
        writeln ('The following operations operate on the complex number Z1');
        writeln;

        z2 := arctan (z1);
        writeln ('arctan:  R=',re(z2),', I=',im(z2));

        z2 := z1 ** 3.141;
        writeln ('**3.141: R=',re(z2),', I=',im(z2));
        { cos, ln, exp, sqrt and sqr exist also }

        z2 := sin(z1);
        writeln ('sin:     R=',re(z2),', I=',im(z2));

        z2 := z1 pow 8;
        writeln ('POW 8:   R=',re(z2),', I=',im(z2));

        z2 := z1 pow (-8);
        writeln ('POW (-8):  R=',re(z2),', I=',im(z2));
     end.

Direct access files:
--------------------

   @@ Not tested.  @@ Write a demo program.

     type
       Dfile = file [ 1 .. 100 ] of integer;
     var
       F : Dfile;
       P, N : 1..100;

   Declares a type for a file that contains 100 integers.

   The following direct access routines may be applied to a direct
access file:

`SeekRead   (F, N);        { Open file in Inspection mode, seek to record N }'
`SeekWrite  (F, N);        { Open file in Generation mode, seek to record N }'
`SeekUpdate (F, N);        { Open file in Update mode, seek to record N }'
`Update (F);               { Writes F^, position not changed. F^ kept. }'
`p := Position (F);        { Return current record number }'
`p := LastPosition (F);    { Return the last record number in file }'
   If the file is open for Inspection or Update, `GET' may be applied.
If the file is open for Generation or Update, `PUT' may be applied.

   @@ GPC acts like the file would always start at record number 0, and
subtracts/adds the lower index from the record number.  If you think
this is incorrect, let me know.

Restricted types:
-----------------

   Extended Pascal defines restricted types as:

     restricted-type = 'restricted' type-name .

   A value of a restricted type may be passed as a value parameter to a
formal parameter possessing its underlying type, or returned as the
result of a function. A variable of a restricted type may be passed as
a variable parameter to a formal parameter possessing the same type or
its underlying type. No other operations, such as accessing a component
of a restricted type value or performing arithmetic, are possible.

     program zap;

     type
        unres_rec =  record
                       a :  integer;
                     end;

        res =  restricted unres_rec;

     var
        r1 :  unres_rec;
        r2 :  res;

        i  :  restricted integer;
        k  :  integer;

       function zap(p : unres_rec) : res;
       var
          ures :  unres_rec;

       begin
          { The parameter is treated as unrestricted, even though the actual
            parameter may be a restricted object }
          ures.a := p.a;

          { Legal to assign a return value }
          zap := ures;
       end; { zap }

     begin
        r1.a := 354;

        { Assigning a restricted return value to a restricted object }
        { @@ Verify if this should really be allowed????? }
        r2 := zap(r1);

        { Passing a restricted object to unrestericted formal parameter is ok }
        r2 := zap(r2);

        { *** The following are illegal *** }
        r2.a := 100;        { field access }
        r1 := r2;        { := source is restricted type }
        r2 := r1;        { := target is restricted type }
        r1 := zap(r2);   { := a restricted return value to unrestricted object }
        i  := 16#ffff;   { := target is restricted type }
        k  := i + 2;     { Arithmetic with restricted type }
     end.

Extended Pascal modules:
------------------------

   @@ Gpc does not yet support:

   * renaming with '`=>''

   * `QUALIFIED' interfaces

   * `PROTECTED' export variables

   * `ONLY'

   * `IMPORT' does not work semantically correct.

   * `EXPORT' does not work semantically correct.

   * exported ranges (compiler calls `abort()')

   * module parameter lists

   Gpc should be able to parse full Extended Pascal module syntax.  But
all the features are not implemented yet.

   You may load one PROGRAM and several MODULEs to make up one pascal
program. A single file may contain zero or more modules and/or zero or
one programs.

   *Please NOTE*: If you have many modules in the same file, the
variable and function declarations are visible after the point they
have been declared in the implementation even if the interface does not
export them. But they do not become visible only by including the
interface to another file and separate compiling that (so you do need
to export them now).  (@@ unfortunately, currently this applies only to
variables  and functions; all other things are visible after the
interface  has been compiled whether or not you exported them.)

   The nicest way to handle the module interface in separate
compilation environment is to use the non-standard

     #include "module-interface.ph"

   feature. You can collect your module interfaces to a single
directory and include them from there by using the "`-I DIR'" switches
to specify the include file search paths to the compiler. (See the GNU
CPP manual for more info).

   There is currently no attempt to avoid name clashes of separate
compiled modules when they are linked together.  (The exported
variables and functions having the same name  in different modules will
clash!!!)

   Sample module code with separate `INTERFACE' and `IMPLEMENTATION'
parts follows:

     MODULE foobar Interface;    (* INTERFACE *)

       EXPORT catch22 = (footype,setfoo,getfoo);

       TYPE footype = integer;

       PROCEDURE setfoo(f: footype);
       FUNCTION  getfoo: footype;

     END. { module foobar interface }


     MODULE foobar Implementation;    (* IMPLEMENTATION *)

       IMPORT StandardInput;
              StandardOutput;

       VAR foo : footype;

       { Note: the effect is the same as the Forward directive would have:
         parameter lists and return types are not "allowed" in the declaration
         of exported routines. }
       PROCEDURE setfoo;
       BEGIN
         foo := f;
       END;

       FUNCTION getfoo;
       BEGIN
         getfoo := foo;
       END;

       TO BEGIN DO
         BEGIN
           foo := 59;
           writeln ('Just an example of a module initializer. See comment below');
         END;

       TO END DO
        BEGIN
          foo := 0;
          writeln ('Goodbye');
        END;

     END. { foobar implementation }

   Alternatively the module interface and implementation may be
combined as follows:

     MODULE foobar;            (* ALTERNATIVE METHOD *)

       EXPORT catch22 = (footype,setfoo,getfoo);

       TYPE footype = integer;

       PROCEDURE setfoo(f: footype);
       FUNCTION getfoo: footype;

       END; { NOTE: this END is required here, even if the
              module-block below would be empty. }

       VAR foo : footype;

       PROCEDURE setfoo;
       BEGIN
         foo := f;
       END;

       FUNCTION getfoo;
       BEGIN
         getfoo := foo;
       END;

     END. { module foobar }

   Either one of the two methods may be used with:

     PROGRAM what(output);

     import catch22;

     BEGIN
       setfoo (999);
       writeln (getfoo);
     END.

   The `INTERFACE' has to be in the same file as the program/module that
uses it's exported names.  Otherwise GPC does not know anything about
it and fails to compile the file.

Somewhat simpler GPC modules are also supported:
------------------------------------------------

   *Note*: this is not supported in Extended Pascal standard.

   This is a simpler module support that does not require exports,
imports, module headers etc.

   These non-standard simple Gpc modules look like (does not have an
export part, does not have a separate  module-block, does not use
import/export features.)

     MODULE foobar;
       TYPE footype = integer;
       VAR foo: footype;

       PROCEDURE setfoo(f: footype);
       BEGIN
         foo := f;
       END;

       FUNCTION getfoo: footype;
       BEGIN
         getfoo := foo;
       END;
     END.

     PROGRAM what(output);

       (* In case the module foobar is loaded from another file *)
       PROCEDURE setfoo(f: footype); External;
       FUNCTION  getfoo: footype;    External;

     BEGIN
       setfoo (999);
       writeln (getfoo);
     END.

Module initialization and finalization:
---------------------------------------

   `TO BEGIN DO' module initialization and `TO END DO' module
finalization constructs are supported if the GNU compiler supports
constructors and destructors in your target machine. (It always does if
you use the GNU Linker).

   If the initialization and finalizations do not work by default, but
you have the GNU Linker, use option `-fgnu-linker' when compiling the
program.

   I re-implemeted the standard I/O handling and now the input and
output can also be used from the initialization and finalization parts.

   @@ Try these, send me bug reports. These are not tested.

Binding of objects to external names:
-------------------------------------

   GPC supports the extended pascal `bind,unbind' and `binding'
operations when applied to files.

   The compiler will currently reject binding of other object types (@@
Perhaps the run time system should do the rejection?)

   GPC implements extensions to the required predefined record type
BindingType:

     BindingType = PACKED_RECORD
                     Bound             : Boolean;
                     Extensions_Valid  : Boolean;
                     Writable          : Boolean;
                     Readable          : Boolean;
                     Existing          : Boolean;
                     Error             : Integer;    { Unused currently }
                     Size              : Integer;    { # of elements or -1 }
                     Name              : String (BINDING_NAME_LENGTH);
                   END;

   The fields `BOUND' and `NAME' are required by the standard. All
other fields are extensions.

   The meaning of the extensions to the `BindingType' record type, and
the value of `BINDING_NAME_LENGTH' is defined in this document, section
IMPLEMENTATION DEFINED FEATURES (E.14). It is a compiler constant, the
run time system accepts any length.

   The `Size' field is a latest addition to `BindingType;' I added that
because the direct access files actually require that the file is not
bigger that the definition; and `lastposition(file)' does not work
before the file is opened. The "`Size'" field can then be used to
determine the size before `open', and if the upper bound of the direct
access file is a variable one should be able to open files of any size
without violating the standard.

   The following is an example of the binding:

     program z(input,output,f);

     var
        f :  text;

     procedure bindfile (varf :  text);
     var
        b : BindingType;

     begin
       unbind (f);
       b := binding (f);
       repeat
         write ('Enter file name:');
         readln (b.name);
         bind (f, b);
         b := binding (f);
         if not b.bound then
           writeln ('File not bound--try again');
       until b.bound;
     end;

     begin

       bindfile (f);

       (* Now the file F is bound to an external file.
        *
        * You can use the implementation defined fields
        * to check if the file is Readable, Writable and
        * if it Exists. These are valid if the.Extensions_Valid
        * field is TRUE.
        *)
     end.

Function pointers:
------------------

   GPC suports also function pointers and calls through them.  This is
a non-standard feature.

     program zap(output);

     type
         proc_ptr = ^ procedure (integer);

     var
         pvar : proc_ptr;

     procedure write_int(i: integer);
     begin
       writeln ('Integer: ',i:1);
     end;

     begin
       (* PVAR points to function WRITE_IT *)
       pvar := &write_int;

       (* Dereferencing a function pointer calls the function *)
       pvar^(12345);
     end.

String catenation:
------------------

   Gpc supports string catenation with the '`+'' operator.  All
string-types are compatible, so you may catenate any chars, fixed
length strings and variable length strings with each other.

     program scat (input, output);

     var
        ch          : char;
        str         : string(100);
        str2           : string(50);
        fstr        : packed array [ 1 .. 20 ] of char;

     begin
        ch   := '$';
        fstr := 'demo';        { padded with blanks }
        write ('Give me some chars to play with: ');
        readln (str);
        str := '^' + 'prefix:' + str + ':suffix:' + fstr + ch;
        writeln ('Len' + 'gth = ', length (str));
        writeln (str);
     end.

Type qualifiers:
----------------

   @ New feature.  @ Currently gpc runtime does not know anything about
these.  @ These may change/or get removed...

   As an extension, GPC allows you to use type qualifiers:
`__byte__'
     8 bit integer

`__short__'
     Short integer (16 bits) or real type (32 bits)

`__long__'
     Long integer or real type

`__longlong__'
     long long integer type (64 bits)

`__unsigned__'
     Unsigned INTEGER type

   The `__unsigned__' works for all integer types, also those that have
been previously declared with some other type qualifier, like
`__short__'. The other qualifiers do not accept types that have already
been modified with a type qualifier.

   The syntax to use the qualifiers:

     type-denoter > TYPE-QUALIFIER type-name

   (The metasymbol `>' means type-denoter has also other meanings)

   Most of these should be done with subranges anyway.  However,
'`__short__ real'' can not be done like that, neither can
'`__unsigned__ integer'' or '`__longlong__ integer''.

     program zap(output);

     type
        byte     = __byte__     integer;
        longint  = __long__     integer;
        float    = __short__    real;
        u_long   = __unsigned__ longint;
        verylong = __longlong__ integer;

     var
       i8  : byte;
       i16 : __short__ integer;
       foo : u_long;
       pi  : float;
       big : verylong;

     begin
       pi  := 3.141592654;
       i16 := 1000;
       big := MaxInt * i16;
       i8  := 127;

       (*
        * Hmm, does not work because constant is treated as an integer,
        * and this is too large. Need a method to specify long constants.
        *
        * What is the syntax in other Pascal compilers? Suggestions, please!
        *

       foo := 16#deadbeef;

        *)
     end.

Accessing command line arguments:
---------------------------------

   The following module accesses the command line with `ParamStr' and
`ParamCount' functions.

   These follow the Un*x semantics, so that
   * `arg[0]' == program name,

   * `arg[1] .. arg[ParamCount-1]' are the arguments.

     MODULE command_line interface;

     EXPORT cmdline = (Max_length, Arg_type, ParamStr, ParamCount);

     CONST
        Max_length = 255;     { Max length of each argument.
                                If some arg is longer, the run time system
                                traps it. }

     TYPE
       Arg_type = String(Max_length);

       FUNCTION ParamCount: Integer;

       FUNCTION ParamStr (arg_num: integer): Arg_type;
     END. { command_line interface }

     MODULE command_line implementation;

       { These are in the GPC runtime library }
       FUNCTION _p_paramcount : Integer; C;
       FUNCTION _p_paramstr (num: Integer; VAR str: String): Boolean; C;

       FUNCTION ParamCount;
       BEGIN
          ParamCount := _p_paramcount;
       END; { ParamCount }

       FUNCTION ParamStr;

       VAR
        Str       : Arg_type;
        Success     : Boolean;

       BEGIN
          Success := _p_paramstr (arg_num, Str);

          (* Should perhaps do something else on failure.
           *
           * Now it returns the empty string, which is also a valid
           * parameter.
           *)
          IF Success THEN
             ParamStr := Str
          else
             ParamStr := '';
       END; { ParamStr }
     END. { command_line implementation }


     { The program below, when compiled with the interface module and
       linked with the implementation module, accesses the command
       line arguments. }

     program zap (output);

     import cmdline;

     var
        counter : integer;

     begin
        writeln ('Program fetches command line arguments and outputs one per line');
        writeln ('Max length of each argument is ',Max_Length:1,' characters');

        for counter := 0 to ParamCount-1 do
           writeln ('Command line arg ',counter:1,' is "',paramstr(counter),'"');
     end.

Borland Extensions in GNU Pascal
================================

   GNU Pascal implements these Borland extensions to the ISO Pascal
language:

   * Program headline:  The `Program' headline may be omitted in TP/BP.
     If the headline is given, the parameters `Input' and `Output' are
     optional.  I modified GPC such that it warns about a missing
     program header, but warns about missing `Input' and `Output'
     parameters only if `pedantic'.

   * Units:  Extended Pascal "Modules" are not too different from TP/BP
     "Units".  The main difference is that modules do not automatically
     export everything mentioned in the interface part, but they need
     additional export clauses.  (Why?  For what does the interface part
     serve if not just to document what should be exported?)  So I im-
     plemented TP/BP "Units".  A Unit exports everything declared in the
     interface section.  The exported interface has the name of the Unit
     and is compatible with Extended Pascal Module interfaces since I
     just used the same routines.

     I got in trouble with "Interface" and "Implementation" which must
     be reserved words in order to compile a Unit.  On the other hand
     side they must remain redefinable to stay compatible to ISO 7185.
     I solved the problem by implementing a mechanism to "enable" and
     "disable" keywords.  When the identifier "Unit" or "Module" is
     read, "Interface" and "Implementation" are enabled as keywords.
     When compiling a valid ISO 7185 program, "Program" must be the
     first identifier, and "Interface" and "Implementation" are disabled
     and have no special meaning.  At the "end." of each compilation,
     everything is set back, so one project can mix ISO 7185 and 10206
     plus Borland standard.

     (By the way:  The "GNU specific" module definition is almost
     identical to the PXSC standard (see below: Operators).  With an
     additional keyword `global' which puts a declaration into an
     export interface with the name of the module, it will be the same.
     I am planning to implement this too.)

   * Protected formal parameters:  Using the same mechanism as above
     (and an additional hack in gpc-lex.c), I solved the "protected"
     problem.  All the following works now:

          Procedure Foo ( protected a, b, c: Integer );      (* 3 args *)
          Procedure Foo ( a, b, c, protected: Integer );     (* 4 args *)
          Procedure Foo ( a, b, protected, c: Integer );     (* 4 args *)
          Procedure Foo ( protected: Integer );              (* 1 arg  *)
          Procedure Foo ( Var protected: Integer );          (* 1 arg  *)
          Procedure Foo ( protected protected: Integer );    (* 1 arg  *)

     Furthermore, I implemented "Const" as an alternative to "protected"
     (according to Borland Pascal)

   * Compiler directives vs. preprocessor:  UCSD and Borland treat
     comments beginning with a '$' immediately following the opening
     `{' or `(*' as a compiler (or preprocessor) directive.  When a
     single character plus a `+' or `-' follows, this is also called a
     compiler switch, often associated with a command-line option.  All
     these directives are case-insensitive.

     For this extension, only the principle idea, not the implementation
     is related to Borland and UCSD.  It is okay (at least between
     Borland and UCSD) to have compiler-dependent compiler-switches.
     Only the include directive (*$I FileName *) is "standard" in both
     (now in three) Pascal dialects.

     Some Borland extensions are - of course not by chance - just an
     alternative notation for C preprocessor directives.  But there are
     differences:  Borland Pascal "preprocessor" definitions go into
     another name space than the program's definitions.  Therefore you
     can (*$D define *) so-called "conditionals" and check them via
     (*$ifdef *), but the program will not see these defines, so macros
     do not exist.  Since it was easier, makes no difference in most
     cases, and is in fact an extension, I left (*$define s*) visible to
     the program.  And I did not forbid to use the other C preprocessor
     directives in the Pascal style.  (Like this, there may be more than
     one in the same line ... )

     I implemented the following directives  (The examples simultane-
     ously illustrate different possible notations):

          (*$B+*)  or  {$B+}            Boolean complete evaluation
          (*$B-*)  or  {$B-}            --short-circuit

          (*$c+*)  or  {$c+}            --c-numbers

          (*$E+,L+,N+*)                 --char-escapes, --lazy-io,
                                        --nested-comments

          (* These switches are local and can change during one compile *)

          {$p+}                         --pedantic
          {$P-}                         end of --pedantic

          (*$I FileName *)              #include "filename.pas"

          {$m Hello! }                  write message "Hello!" to stderr

          (*$D FOO bar *)               #define FOO bar
          {$define CMULB}               #define CMULB

          (*$include <hello.ph> *)      #include <hello.ph>

                                        #ifdef FOO
          (*$ifdef FOO*) ... (*$endif*)   ...
                                        #endif

          (* ... and all the other C preprocessor directives ... *)

     By the way:  I implemented an option -borland-pascal symmetrically
     to -extended-pascal and -object-pascal.  But I couldn't figure out
     what they serve for since I didn't notice any difference in the
     compiler's behaviour with and without these options.  Nevertheless,
     I made -borland-pascal to switch on -nested-comments, so it has at
     least one effect :-).

   * Bit manipulations:  The TP/BP bit shift operators "shl" and "shr"
     do now exist in GPC; bitwise "and", "or", "xor", and "not" for
     integer values are allowed.  Warning is given, if "pedantic" -
     like for all non-ISO extensions.

          2#100101 and ( 1 shl 5 ) = 2#100000

     I could not restrain, but also implemented "and", "or", "xor" and
     "not" as "procedures":

          x:= 7;
          and ( x, 14 );          (* yields 6 *)
          xor ( x, 3 );           (* yields 5 *)

     (This is a feature I often missed with Borland Pascal.)

   * Increment, decrement:  The TP/BP built-in Procedures "inc" and
     "dec" do now exist in GPC.

          Var
            x: Integer;
            c: Char;

          inc ( i );      (* i:= i + 1; *)
          dec ( i, 7 );   (* i:= i - 7; *)
          inc ( c, 3 );   (* c:= chr ( ord ( c ) + 3 ); *)

   * Min, max:  These are a GNU extension and work for reals as well as
     for ordinal types.  Mixing of reals and integers is okay (result
     is real).

   * Memory management:  TP/BP allows dynamic memory management with
     `GetMem' and `FreeMem':

          GetMem ( MyPtr, 1024 );       FreeMem ( MyPtr, 1024 );

     GPC now supports this and also a "function-style" call to `GetMem':

          MyPtr:= GetMem ( 1024 );

     (see also: New in context of Object Orientated Programming)

     One somehow strange feature of Borland is *not* supported:  You can
     free parts of a variable with FreeMem, while the rest is still used
     and can be FreeMem'ed later by another pointer:

          Type
            Vector = array [ 0..65535 ] of Integer;
            VecPtr = ^Vector;

          Var
            p, q: VecPtr;

            ...

            GetMem ( p, 1024 * SizeOf ( Integer ) );
            q:= &p^ [ 512 ];
            ...
            FreeMem ( p, 512 * SizeOf ( Integer ) );
            ...
            FreeMem ( q, 512 * SizeOf ( Integer ) );

   * Hex numbers:  TP/BP hex numbers with a leading `$' are now
     supported by GPC parallel to base#number.

          $cafe = 2#1100101011111110

   * Typed constants vs. initialized variables:  TP/BP "typed constants"
     can now be used in GPC too.  Currently, they are just initialized
     variables (as in TP/BP), but they will be changed at least to read-
     only variables.  (Or at least a warning will be given when trying
     to change their values.)  I recommand to use typed constants only
     for effective constants and use Extended Pascal initialized
     variables as initialized variables.

          Const
            A: Integer = 7;
            B: array [ 1..3 ] of Char = ( 'B', 'a', 'r' );
               (* TP/BP also would also understand " = 'Bar'; ". *)
            Foo: record
              x, y: Integer;
            end (* Foo *)
              = ( x: 3; y: 4 );

     Borland and ISO style for the right-hand side are both supported.

     Once working on this, I also implemented VAX Pascal variable ini-
     tializing with `:=' (as an alternative to `value') and also with
     `=' (like in Borland "initialized variables").

     Warning: This was one of my last changes and is not yet stable.  I
     could not, for example, recover from 3 shift/reduce conflicts and 1
     reduce/reduce conflict.  This causes trouble when the type (for
     example a subrange) ends up with an expression such that the parser
     takes the `=' as a relational operator.

   * Absolute variables:  The "absolute" clause does now exist in GPC,
     but only for superposition of variables, not for giving an abso-
     lute address for variables.  (The latter application is useful only
     in the DOS platform anyway.)

          Procedure ReadVar ( Var x: Void; TypeChoice: Char );

          Var
            xInt: Integer absolute x;
            xChar: Char absolute x;
            xStr: String ( 80 ) absolute x;

          begin (* ReadVar *)
            ...
          end (* ReadVar *);

   * AsmName directive:  As a GNU extension, I implemented a new direc-
     tive `AsmName'.  While the `extern' directive capitalizes the first
     character of the declared name and the `C' directive makes every-
     thing lowercase, this directive allows the user to specify the
     assembler name as a string constant:

          Function MyFunc: Integer; AsmName 'MyPrettyFunc_';

     With this extension it is possible to access all external
     functions, for example the XT interface functions, and not only
     those written in lowercase.

     My first idea to use `external' for this purpose (to avoid name
     space pollution) conflicts with another Borland extension not yet
     implemen- ted:  In Borland Pascal, the declaration

          Procedure Foo; external 'MyLib';

     means that the procedure Foo should be imported by name ("Foo")
     from a dynamic link library "mylib.dll".

   * Open arrays:  Borland Pascal "open array" formal parameters are now
     implemented into GPC.  Within the function body, they have integer
     type index with lower bound 0.  Currently, a warning about invalid
     pointer conversion is given; code works.  (Conformant arrays are
     probably better but are incompatible to other languages.)

   * Address operator:  The address operator is "`@'" in TP/BP.
     Implemented into GPC as an alternative to "`&'".

   * Variant records:  Variant records may now be constructed with a
     subrange type, too.  E.g. "`case 1..3 of ...'" is allowed now.

   * Objects (classes):  The Borland Pascal Object Extensions are almost
     fully implemented into GPC.  This includes inheritance, virtual and
     non-virtual methods, constructors, destructors, pointer compati-
     bility, extended `New' syntax (with constructor call and/or as a
     "function"), extended `Dispose' syntax (with destructor call).

     The Borland "standard" is different from the ISO draft (which I
     have never seen), but it should not be too difficult now to im-
     plement that too (plus the Borland Delphi Object Extensions which
     *might* be identical to the ISO draft).

          Type
            MyParentPtr = ^MyParentObj;
            MyPtr = ^MyObj;

          MyParentObj = object
            ...
          end (* MyParentObj *);

          MyObj = object ( MyParentObj )
            a, b, c: Integer;
            Constructor Init;
            d, e: Char;    (* GNU extension: Data fields *)
            Destructor Fini; virtual;(* and methods may be mixed   *)
            Procedure Foo ( x: Integer );
            Function Bar: Char; virtual;
            (* "private" is not (yet) implemented *)
          end (* MyObj *);

          Var
            My: MyParentPtr;

          ...

          Constructor MyObj.Init;

          begin (* MyObj.Init *)
            inherited Init;
            a:= 0;
            MyParentObj.Bar;
          end (* MyObj.Init *);

          ...

          My:= New ( MyPtr, Init );
          My^.Foo ( 3 );
          Dispose ( My, Fini );
          New ( My, Init );
          with My^ do
            writeln ( Bar );

     I first tried to recycle parts of the C++ and/or ObjC frontend, but
     I gave up after a few hours.  Since I was not able to understand
     how they work, I re-invented and implemented my own Object frontend
     - the third one I noticed in the GNU compiler family.  Sorry.

   * Operators:  This extension is not from Borland but from the PXSC
     (Pascal eXtensions for Scientific Calculations) standard and allows
     redefinition of operators.  It must explicitly be enabled either by
     the compiler directive $X+ ("extended syntax") or by a command line
     option "-pascal-sc" or "-extended-syntax".

          (*$X+*)

          Type
            Vec3 = record
              x, y, z: Real;
            end (* Vec3 *);

          Var
            a, b, c: Vec3;

          Operator + ( u, v: Vec3 ) w: Vec3;

          begin (* Vec3 + Vec3 *)
            w.x:= u.x + v.x;
            w.y:= u.y + v.y;
            w.z:= u.z + v.z;
          end (* Vec3 + Vec3 *);

          ...

          c:= a + b;

     Extended Pascal would require an equal sign before the return value
     variable specification (`w' in the above example) while PXSC for-
     bids it.  Therefore I allow the equal sign to be present or not,
     both in a function declaration as well as in an operator
     declaration.


File: ^.!gcc.docs.pascal.gpc,  Node: Extended Pascal,  Next: Borland Pascal,  Prev: Extensions,  Up: Top

About Pascal and Extended Pascal languages
******************************************

   Pascal is a well-known programming language and hardly needs to be
described here.  Notice, however, that some people's idea of Pascal is
affected by acquaintance with such products as Turbo Pascal which
differ from the Pascal standard and provide a lot of nonstandard
extensions (some of which are compatible with the Extended Pascal
standard).  Moreover, it is worth mentioning that the ISO Pascal
standard defines two levels of the language, level 0 and level 1; the
only difference between the levels is that level 1 supports the
so-called conformant array schemas in parameter declarations.

   Extended Pascal is a standardized language which contains so
significant extensions to Pascal that it is best regarded as a new
language.  It is currently not very well known, and computer vendors do
not seem to be eager to provide compilers for it.  Thus, there is
social need for GNU Pascal supporting Extended Pascal.

A comparison of Borland Turbo Pascal with Extended Pascal
=========================================================

   As mentioned earlier, Turbo Pascal does not conform to any of the
Pascal standards.  If you carefully chose a subset of unextended
Pascal, you may be able to port code if you're lucky/careful.

   To be fair, Turbo Pascal has some wonderful features that make it
very powerful in the environments in which it runs.  However, some of
those features are of little use on non Windows/DOS platforms and
probably are not good candidates for standardization.

   There are several Turbo Pascal features which are semantically
similar to features in unextended Pascal or Extended Pascal.  Here is a
list of mappings between Turbo Pascal features and Extended Pascal
features:

   * Case constructs

       a. Extended Pascal uses `otherwise' instead of `else'.

          *Borland Pascal*
               case c of
                 'A' : ;
                 'B' : ;
                 else ...;
               end;

          *Extended Pascal*
               case c of
                 'A' : ;
                 'B' : ;
                 otherwise ...;
               end;

       b. Missing cases cause Extended Pascal compilers to halt. In the
          case statement above if you had no `otherwise' clause and
          char c had the value 'C', you got an error (note, this would
          be unnoticed in Borland Pascal).


   * Procedure and function types and variables

     Here is an area of subtle differences.  Turbo Pascal has true
     procedure/function types but doesn't have standard Pascal's
     procedural/functional parameters.

     *Borland Pascal*
          type
            CompareFunction = function(Key1, Key2 : string) : integer;

          function Sort(Compare : CompareFunction);
          begin
            ...
          end;

     *Extended Pascal*
          function Sort(Compare : function(Key1, Key2 : string) : integer);
          begin
            ...
          end;

     Moving from Turbo Pascal to Extended Pascal might be difficult if
     the Turbo Pascal program saves, compares, trades, etc. procedure
     values.  For example, an array of procedure values isn't possible
     in Extended Pascal.  Moving the other way is a little easier as
     show by the above examples.

   * Strings

       a. Borland Pascal's string type has a special case, namely
          `string' without a length meaning the same as `string[255]'.
          There is no default in Extended Pascal so you have to change
          all string types to `string(255)'. Example:

               var
                 s : string;

          becomes:
               var
                 s : string(255);

          Note also that you have to use parentheses instead of
          brackets.

       b. A nice pitfall is the pointer to string as in:

               type
                 PString = ^String;

          In Extended Pascal this is a pointer to a schema type! Don't
          forget to translate this to:

               type
                 string255 = string(255);
                 PString = ^string255;

          If you indeed want to use String as a schema pointer you can
          define things like:

               type
                 MyStr : ^String;
               begin
                 New(MyStr, 1024);
               end;

          to allocate 1024 bytes of string space.

       c. As you could see above, Extended Pascal has no 255 byte limit
          for strings. It is however save to assume a limit of about
          32000 bytes. At least Prospero's Extended Pascal limits
          strings to 32760 bytes. GNU Pascal seems to allow larger
          strings.  DEC Pascal limits strings to 65535 bytes.


   * Constant variables

       a. Extended Pascal translates Borland's gruesome:

               const
                 i:integer = 0;

          to:

               var
                 i : integer value 0;

       b. You can also assign initialization values to types. Like:

               type
                 MyInteger = integer value 0;

               var
                 i : MyInteger;

          All variables of type MyInteger are automatically initialized
          to 0 when created.

       c. Constant arrays of type string are translated from:

               const
                 MyStringsCount = 5;
               type
                 Ident = string[20];
               const
                 MyStrings : array [1..MyStringsCount] of Ident = (
                               'EXPORT', 'IMPLEMENTATION', 'IMPORT', 'INTERFACE',
                               'MODULE');

          to:

               const
                 MyStringsCount = 5;
               type
                 Ident = string(20);
               var
                 MyStrings : array [1..MyStringsCount] of Ident value [
                   1:'EXPORT'; 2:'IMPLEMENTATION'; 3:'IMPORT';
                   4:'INTERFACE'; 5:'MODULE'];

          There seem to be pros and cons to each style.

          Some folks don't like having to specify an index since it
          requires renumbering if you want to add a new item to the
          middle.  However, if you index by an enumerated type, you
          might be able to avoid major renumbering by hand.


   * Variant records

     The following construction is not allowed in Extended Pascal:
          type
            PersonRec = record
              Age : integer;
              case EyeColor : (Red, Green, Blue, Brown) of
                Red, Green : (Wears_Glasses : Boolean);
                Blue, Brown : (Length_of_lashes : integer);
              end;
            end;

     The variant field needs an explicit type. Code this as:

          type
            EyeColorType = (Red, Green, Blue, Brown);
            PersonRec = record
              Age : integer;
              case EyeColor : EyeColorType of
                Red, Green : (Wears_Glasses : Boolean);
                Blue, Brown : (Length_of_lashes : integer);
              end;
            end;

   * Units

       a. You can translate units almost automatically to Extended
          Pascal Modules, taking into account some differences of
          course.

          Extended Pascal does not automatically export everything named
          in a module, but you have to create seperate export clauses.

          For example translate the following unit:

               unit A;

               interface

               uses
                 B, C;

               procedure D;

               implementation

               procedure D;
               begin
               end;

               end.

          to this module:

               module A interface;

               export
                 A = (D);

               import
                 B;
                 C;

               procedure D;

               end.

               module A implementation;

               procedure D;
               begin
               end;

               end.

          You can have one or more export clauses and the name of an
          export clause doesn't have to be equal to the name of the
          module.

          You also see in this example how to translate the Borland
          Pascal "uses" clause to the Extended Pascal "import" clause.

       b. Borland Pascal allows you to have code in a unit that is
          executed once, at startup, to initialize things. You can
          translate this to Extended Pascal's "to begin do ..end"
          structure.

          *Borland Pascal*
               unit A;

               interface

               implementation

               begin
                 { do something }
               end.

          *Extended Pascal*

               module A interface;
               end.

               module A implementation;

               to begin do begin
                 { do something }
               end;

               end.

          Extended Pascal also has a `"to end do .... end"' so you can
          translate `Exit' handlers also.


   * Files

     Extended Pascal treats files quite differently as Borland Pascal.
     I'm not going to treat file pointers, Get and Put here, but
     instead I focus on special Extended Pascal features.

     In Borland Pascal you can read any text file as follows:

          var
            t : text;
            Line : string;
          begin
            Assign(t, 'MYTEXT.TXT');
            Reset(t);
            while not eof(t) do  begin
              readln(t, Line);
              writeln(Line);
            end;
          end;

     The `Assign' function associated the textfile `T' with the file
     `MYTEXT.TXT'.

     In Extended Pascal, files are considered entities external to your
     program. External entities, which don't need to be files, need to
     be bound to a variable your program. Any variable to which
     external entities can be bound needs to be declared bindable. So
     the variable declaration of t becomes:

          var
            t : bindable text;

     Extended Pascal has the bind function that binds a variable with
     an external entity.  Here is an Extended Pascal procedure that
     emulates the Assign procedure in Turbo Pascal.

          procedure Assign(var t : text; protected Name : string);
          var
            b : BindingType;
          begin
            unbind (t);
            b := binding (t);
            b.Name := Name;
            bind (t, b);
            b := binding (t);
          end;

     Comments: the unbind procedure unbinds a bindable variable from
     its external entity. If it is not bound, nothing happens. The
     binding function initializes b. We call binding to set some fields
     of the BindingType record. Next we set the name field to the name
     of the file. Calling bind will bind t to the external entity. If
     we now call binding again, we get the current state of t's binding
     type. We can now check for example if the bind has succeeded by:

          if not b.bound then
            { do error processing }

     Note that Prospero's Pascal defaults to creating the file if it
     does not exists! You need to use Prospero's local addition of
     setting `b.existing' to `true' to work-around this.

     I've not worked with binary files enough, so no advice yet on how
     to access them, but you access them much the same.

     As last an example of getting the size of a file.

          function FileSize(filename : String) : LongInt;
          var
            f : bindable file [0..MaxInt] of char;
            b : BindingType;
          begin
            unbind(f);
            b := binding (f);
            b.Name := filename;
            bind(f, b);
            b := binding(f);
            SeekRead(f, 0);
            if empty(f)
              then  file_size := 0
              else  file_size := LastPosition(f) + 1;
            unbind(f);
          end(*file_size*);

     Prospero's Extended Pascal has a bug in this case. Replace the
     MaxInt in the type definition of f by a sufficiently large
     integer. GNU Pascal works correct in this case.


File: ^.!gcc.docs.pascal.gpc,  Node: Borland Pascal,  Next: FPK Pascal,  Prev: Extended Pascal,  Up: Top

From Borland Pascal to GNU Pascal
*********************************

   This chapter is intended to be a QuickStart guide for programmers
who are familiar with Borland Pascal, version 7 for DOS protected mode.
Other versions don't differ too much but this one is the very last DOS
version Borland has published.

* Menu:

* Borland compatibility::
* There is no IDE!::
* Comments and compiler directives::
* Units; GPI files and AutoMake::
* Optimization::
* Debugging::
* GPC inline assembler::
* Objects::
* Strings::
* Typed constants::
* Bit; byte and memory manipulation::
* User-defined operators::
* Data types::
* Files::
* Built-in constants::
* Built-in operators::
* Built-in Procedures and Functions::
* Parameters::
* Miscellaneous::


File: ^.!gcc.docs.pascal.gpc,  Node: Borland compatibility,  Next: There is no IDE!,  Up: Borland Pascal

Borland compatibility
=====================

   Unlike other FreeWare compilers, GNU Pascal is *not* intended to be
100% Borland compatible.  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.  Some other differences are so minimal that we have more
important things to do than to implement them.

   However if you want to contribute to GNU Pascal by eliminating holes
in GPC's Borland compatibility, be welcome in the GNU Pascal
development team!  See *Note How to Contribute:: for details.


File: ^.!gcc.docs.pascal.gpc,  Node: There is no IDE!,  Next: Comments and compiler directives,  Prev: Borland compatibility,  Up: Borland Pascal

There is no IDE!
================

   It is one of the most annoying points about GPC that there is no
Integrated Development Environment like BP.EXE at the moment.  We are
working on it, but this will take some time, especially because GNU
Pascal is a *portable* compiler intended to run under a large variety
of operating systems in the same manner.  Please be patient--or offer
your help!  (For the moment, you can try to use Borland's IDE for GNU
Pascal--see below.)

   The GNU Pascal Compiler, GPC, is called about like the command-line
version of the Borland Pascal Compiler, BPC.  Edit your source file(s)
with your favorite ASCII editor (e.g. the Borland IDE), then call GNU
Pascal with a command line like

       C:\GNU-PAS> gpc hello.pas

on your DOS or OS/2 box or

       myhost/home/joe/gnu-pascal> gpc hello.pas -o hello

on your UNIX (e.g. Linux or FreeBSD) box.  Don't omit the suffix
`.pas':  GPC is a common interface for a Pascal compiler, a C, ObjC and
C++ compiler, an assembler, a linker, and perhaps a Modula and FORTRAN
compiler.  From the extension of your source file GPC figures out which
processor to run.

   The `-o' is a command line option which tells GPC how the executable
has to be named.  This is not necessary for DOS and OS/2, so we omit it
in this file from now on.

   Note that GPC is case-sensitive concerning file names, so it will
*not* work if you type

       C:\GNU-PAS> GPC HELLO.PAS

   GPC is a very quiet compiler and doesn't print anything on the
screen unless you request it or there is an error.  If you want to see
what is going on, invoke GPC with additional options:

       -Q            "don't be quiet"  (or: Quassel-Modus in German)

means that GPC prints out the names of procedures and functions it
processes, and

       --verbose

means that GPC informs you about the stages of compilation, i.e.
preprocessing, compiling, assembling, and linking.

   One example (this time for OS/2):

       [C:\GNU-Pascal] gpc --verbose -Q hello.pas

   Throughout this chapter, we will tell you about a lot of
command-line switches.  They are all invoked this way.

   After compilation, there will be an executable `hello' file in the
current directory.  (`hello.exe' with DOS and OS/2.)  Just run it and
enjoy.  If there are errors, GNU Pascal will not stop compilation after
the first one--as Borland Pascal does--but try to catch them all in one
compilation.  If you get more error messages than your screen can hold,
you can catch them in a file (e.g. `gpc.out') in the following way:

       gpc hello.pas 2>gpc.out

   This works with DOS, OS/2 and any bash-like shell under UNIX.

   However, you can use Borland's IDE for GNU Pascal on the DOS
platform:  Install the GNU Pascal Compiler in the Tools menu (via
Options/Tools).

       Name:       GNU Pascal
       Path:       gpc
       Arguments:  $SAVE ALL --verbose -Q $NAME($EDNAME).pas
       HotKey:     Shift+F9

   Note once more that GPC is case-sensitive, so it is important to
specify `.pas' instead of the `.PAS' Borland Pascal would append
otherwise!

   You can include more command-line arguments to GNU Pascal (e.g.
`--automake'; see below) as you will learn more about them below.

   Because Borland Pascal will try to recompile your program if you use
its `run' menu function, you will need another "tool" to run your
program:

       Name:       run program
       Path:       command.com
       Arguments:  /c $NAME($EDNAME)
       HotKey:     Shift+F10


File: ^.!gcc.docs.pascal.gpc,  Node: Comments and compiler directives,  Next: Units; GPI files and AutoMake,  Prev: There is no IDE!,  Up: Borland Pascal

Comments and compiler directives
================================

   According to ISO 7185 and ISO 10206 standard, GNU Pascal recognizes
by default comments opened with `(*' and closed with `}'.  With Borland
Pascal, both types of comments can be nested, so you will probably have
sources where passages containing comments are "commented out".

   To use this with GPC, you have to "switch on" nested comments either
by a command-line option, or by a compiler directive:

       --nested-comments            {$N+}    (*$N+*)

   The $N directive also exists in BP but has another meaning.  The
same holds for most of GPC's other compiler directives (also
corresponding to command-line options in most cases):

       --short-circuit     $B+ $B-  like in Borland Pascal:
                                    $B- means short-circuit Boolean
                                    operators; $B+ complete evaluation

       --c-numbers         $C+ $C-  enable/disable C-style octal 0177
                                    and hexadecial 0xFF numbers

       --char-escapes      $E+ $E-  enable/disable C-style character
                                    escape sequences in strings

       --nested-comments   $N+ $N-  see above

       --pedantic          $P+ $P-  give/don't give warnings about
                                    violations of ISO 7185
                                    Standard Pascal

                           $W+ $W-  enable/disable warnings

                           $X+ $X-  enable/disable extended syntax
                                    (function return value ignore,
                                    operator definitions)

       {$I FileName }               include filename.pas or
                                    filename.p (make it lowercase)

       {$include "filename.pas"}    include (case-sensitive)

       {$include <filename.pas>}    the same, but don't search in
                                    current directory

       {$M Hello!}                  write message "Hello!" to error
                                    device during compilation

       {$D GNU}                     define GNU (for conditional
       {$define GNU}                compilation)

       -D GNU                       the same in command line

       {$D loop while true do}      define "loop" to be "while
                                    true do" as a macro like in C.
                                    It is case-sensitive.

       {$ifdef GNU}                 conditional compilation
         ...                        (like in Borland Pascal).
       {$else}                      GPC predefines the symbol
         ...                        __GPC__ (with two leading
       {$endif}                     and trailing underscores).

   You also can use C-style preprocessor directives, e.g. #include.

   As in Borland Pascal, `{$...}' and `(*$...*)' are equivalent.


File: ^.!gcc.docs.pascal.gpc,  Node: Units; GPI files and AutoMake,  Next: Optimization,  Prev: Comments and compiler directives,  Up: Borland Pascal

Units, GPI files and AutoMake
=============================

   You can use Units in the same way as in Borland Pascal.  However,
there are some differences, problems and new features.  (Please report
the bug if something doesn't work.)

   Concerning the syntax of a Unit, you can, if you want, use Extended
Pascal syntax to specify a Unit initializer, i.e.  instead of writing

       begin
         ...
       end.

at the end of the Unit, you can get the same result with

       to begin do
         begin
           ...
         end (* to begin *);

and there also exists

       to end do
         begin
           ...
         end (* to end *);

   which specifies a finalization routine.  Use this instead of Borland
Pascal's exit procedures.  You also can specify an order in which
initializers are run--see *Note Extensions:: and *Note Extended
Pascal:: for more about this.  There you can also find information
about Extended Pascal Modules, an alternative to Units.

   At the moment, there are no qualified identifiers, so take care
about name clashes between different Units.

   When GPC compiles a Unit, it produces two files: an `.o' object file
(compatible with other GNU compilers such as GNU C) plus a precompiled
Interface which resides in a `.gpi' file.

   GPC does not automatically recognize that something is a Unit and
cannot be linked; you have to tell this by a command line switch:

       -c            only compile, don't link.

   For example, to compile two units, use:

       gpc -c myunit1.pas myunit2.pas

   Of course, one of the purposes of writing Units is to compile them
separately.  However, GNU Pascal allows you to have one or more Units
in the same source file (producing only one `.o' file but separate
`.gpi' files).  You even can have a Program and Units in one and the
same source file; in this case, no `.o' file at all is produced.

   You can use the above as a workaround (*$include the Unit *) in case
something goes wrong with the .gpi mechanism.  (It is a new feature in
GPC 2.7.2 and may be unstable.)

   When you have all Units compiled and want to compile the Program,
specify the `.o' files in the command line:

       gpc hallo.pas myunit1.o myunit2.o

   You also can specify the program and the units in one command line:

       gpc hallo.pas myunit1.pas myunit2.pas

   As an alternative to manually compiling and specifying object files,
you can use GPC's AutoMake feature.  (WARNING: This is a new feature in
GPC 2.7.2 and may be unstable!)  With an additional command-line
argument

       gpc --automake hallo.pas

   GPC tries to behave like Borland Pascal's `make' facility and
automatically recompiles Units the source of which has been changed.
It also works if an included file has been changed.

   To pass arguments to the compilation of Units, specify them in a
string surrounded by quotation marks after `--automake='.  For example,
if you want to give the `--verbose' argument not only at top level but
also for (re)compilation of Units, use:

       gpc --verbose --automake="--verbose" hallo.pas


File: ^.!gcc.docs.pascal.gpc,  Node: Optimization,  Next: Debugging,  Prev: Units; GPI files and AutoMake,  Up: Borland Pascal

Optimization
============

   GNU Pascal is a 32 bit compiler with excellent optimization
algorithms (which are identically the same as those of GNU C).  There
are three official optimization levels, specified by the command line
options `-O', `-O2', and `-O3'.  Actually, this goes up to `-O6', but
levels above `-O3' are experimental (as far as I know).

   One example:

       Program Test;

       Var
         A, B: Integer;

       begin
         A:= 3;
         B:= 4;
         writeln ( A + B );
       end.

   When GNU Pascal compiles this program with optimization, it
recognizes that the argument of writeln is the constant 7--and
optimizes away the variables `A' and `B'.

   For more about optimization, see the GNU C documentation.


File: ^.!gcc.docs.pascal.gpc,  Node: Debugging,  Next: GPC inline assembler,  Prev: Optimization,  Up: Borland Pascal

Debugging
=========

   The command line option `-g' specifies generation of debugging
information for GDB, the GNU debugger.  GDB is not as comfortable as
the Turbo Debugger, but it has the same abilities but one:  The program
being debugged is slowed down.  For more information about GDB, call it
with `gdb' and type in the `help' command.

   GDB has one very nice feature which might even make up for the
slowing-down problematic:  When a GNU-compiled program crashes, it puts
out a `core' file.  When you say "target core core" to the GNU
debugger, it reads the core file and can tell you the address of the
crash, the contents of variables and of the stack, and so on.

   Sometimes it is nice to have a look at the assembler output of the
compiler.  When you specify the `-S' command line option, GPC produces
an `.s' file instead of an `.o' file which contains assembler source
for your program.  More about this in the next section.


File: ^.!gcc.docs.pascal.gpc,  Node: GPC inline assembler,  Next: Objects,  Prev: Debugging,  Up: Borland Pascal

GPC inline assembler
====================

   GNU Pascal has an inline assembler, but it is quite different from
Borland's one.  I have not yet found reasonable documentation about the
use of this assembler, but I found out the following:

   The syntax is

       asm ( 'movl $12345678, %eax' );
       asm ( 'movl %eax, %edx' );

   to move the (hex) value `$12345678' to the EAX register and then to
the EDX register.  The String argument of the asm "procedure" is passed
as a string to the assembler stage of the compilation.  Note that the
order of operands is reversed with respect to the order you know from
other Intel assemblers and that the size of the arguments is appended
to the mnemonic as a suffix b (byte), w (word = 2 bytes), or l (long =
4 bytes).

   You can learn about the GNU assembler syntax when compiling your
program with `-S' (see above) and looking into the resulting assembler
source.

   To access Pascal symbols from the assembler, do something like

       asm ( 'movl %%eax, %0' : : 'rm' ( MyVariable ) );

   Here, the % signs in front of the register names are doubled because
% gets some special meaning.  The 'rm' means that the operand may be in
a register or in memory.

   (If somebody knows more about the GNU assembler syntax, please,
please, please explain it to me or point me to some reasonable
documentation about it! <[e-mail]>)


File: ^.!gcc.docs.pascal.gpc,  Node: Objects,  Next: Strings,  Prev: GPC inline assembler,  Up: Borland Pascal

Objects
=======

   Objects in the Borland Pascal 7.0 notation are implemented into GNU
Pascal with the following differences:

   * the "private" directive does not work,

   * data fields and methods may be mixed:
            MyObj = object
              x: Integer;
              Procedure Foo; virtual;
              y: Real;
              Function Bar: Char;
            end (* MyObj *);


File: ^.!gcc.docs.pascal.gpc,  Node: Strings,  Next: Typed constants,  Prev: Objects,  Up: Borland Pascal

Strings
=======

   Strings are "Schema types" in GNU Pascal which is something more
complicated than Borland-style strings.  For variables, you cannot
specify just `String' as a type (always specify the maximum length);
for parameters you can.  There is no 255 length limit.  According to
Extended Pascal, the maximum string length must be in (parantheses);
GNU Pascal accepts [brackets], however.

   For more about Strings and Schema types see *Note Extensions:: and
*Note Extended Pascal::.

   String-handling functions (see *Note Extensions::) are different in
both dialects but can approximately be mapped on each other:

       Borland Pascal          GNU Pascal

       length                  length
       Pos                     Index
       Str                     WriteStr
       Val                     ReadStr
       Copy                    SubStr, MyStr [ 2..7 ]
       MyStr [ 0 ]:= #7;       Trim
         -                     EQ, NE, LT, LE, GT, GE
       Insert                    -
       Delete                    -

   It should not be difficult to write a compatibility Unit--if you do
so, please send it to us!


File: ^.!gcc.docs.pascal.gpc,  Node: Typed constants,  Next: Bit; byte and memory manipulation,  Prev: Strings,  Up: Borland Pascal

Typed constants
===============

   GNU Pascal supports Borland Pascal's "typed constants" but also
Extended Pascal's initialized variables:

       Var
         x: Integer value 7;

   When a typed constant is misused as an initialized variable, a
warning is given.

   Initialization of structured variables (typed constants) is not yet
stable.

   When you want a local variable to preserve its value, define it as
`__static__' instead of using a typed constant:

       Procedure Foo;

       Var
         x: __static__ Real;

       begin (* Foo *)
         (* x keeps its value between two calls to this Procedure *)
       end (* Foo *);

   Remark: If you don't like underscores, you can use the (*$define *)
mechanism to get rid of them:

       (*$define static __static__ *)


File: ^.!gcc.docs.pascal.gpc,  Node: Bit; byte and memory manipulation,  Next: User-defined operators,  Prev: Typed constants,  Up: Borland Pascal

Bit, byte and memory manipulation
=================================

   The (non-standard) bitwise operators `shl', `shr', `and', `or',
`xor' work in GNU Pascal like in Borland Pascal.  As an extension, you
can use them as "procedures", for examples

       and ( x, $0000FFFF );

   as an alternative to

       x:= x and $0000FFFF;

   Instead of the Borland-specific notation `$ABCD' for hexadecimal
numbers you also can use Extended Pascal notation:

        2#11111111   for a binary,
        8#177        for an octal,
       16#FF         for a hexadecimal number,

   and so on up to a basis of 36.

   Inc and dec are implemented like in Borland Pascal; pred and succ
are generalized according to Extended Pascal:

       a:= succ ( a, 5 );

   Absolute variables work only in the context of overloading with
other variables, not in the context of specifying an absolute address.
The Mem and Port arrays don't exist in GNU Pascal.

   Borland Pascal's procedures `FillChar' and `move' are not built-in
into GNU Pascal.  However, you can write them by yourself using untyped
Var parameters (see Sec. `Data types').


File: ^.!gcc.docs.pascal.gpc,  Node: User-defined operators,  Next: Data types,  Prev: Bit; byte and memory manipulation,  Up: Borland Pascal

User-defined operators
======================

   GNU Pascal allows the user to define operators according to the
Pascal-SC syntax:

       (*$X+*)

       Type
         Point = record
           x, y: Real;
         end (* Point *);

       Operator + ( a, b: Point ) c: Point;

       begin (* Point + Point *)
         c.x:= a.x + b.x;
         c.y:= a.y + b.y;
       end (* Point + Point *);

   It is necessary to enable "extended syntax" `(*$X+*)' when defining
operators.

   The Pascal-SC operators `+>', `+<', etc. for exact numerical
calculations are not implemented, but you can define them.  If you
write a module which really implements these operators, please send it
to us, so we can include it into the next distribution.

   (And if you know more about modules in Pascal-SC than just their
existence, please contact us either!  We could probably easily
implement them if we knew how they look like.  Something quite close to
Pascal-SC modules already *is* implemented as "GNU specific modules".)


File: ^.!gcc.docs.pascal.gpc,  Node: Data types,  Next: Files,  Prev: User-defined operators,  Up: Borland Pascal

Data types
==========

   * Generic Pointer:  There is no built-in untyped Pointer in GNU
     Pascal.  Use `^Void' to define it.

   * Integer types:  There is no built-in Byte, Word, etc. in GNU
     Pascal.  Use the modifiers `__byte__', `__short__', `__long__' and
     `__unsigned__' (described in *Note Extensions::) to define them.

            Borland Pascal          GNU Pascal

            __byte__ Integer
            Integer                 __short__ Integer
            LongInt                 Integer = __long__ Integer
            Comp                    __longlong__ Integer
            Byte                    __unsigned__ __byte__ Integer
            Word                    __unsigned__ __short__ Integer
              -                     __unsigned__ __long__ Integer
              -                     __unsigned__ __longlong__ Integer

     Real types: There is no built-in `Single', `Double', `Extended' in
     GNU Pascal; Real has 8 bytes on an Intel-x86 machine.  Use
     `__short__ Real' to define `Single', `__long__ Real' to define
     `Extended'.

            Borland Pascal          GNU Pascal

            Single                  __short__ Real
            Real                      -
            Double                  Real
            Extended                __long__ Real
            Comp                    __longlong__ Integer

   * Complex numbers:  According to Extended Pascal, GNU Pascal has
     built-in complex numbers.

   * Instead of procedural types, GNU Pascal has pointers to procedures:

              Type
                FuncPtr = ^Function ( Real ): Real;

     Furthermore, GNU Pascal supports Standard Pascal's procedural
     parameters--see below.


File: ^.!gcc.docs.pascal.gpc,  Node: Files,  Next: Built-in constants,  Prev: Data types,  Up: Borland Pascal

Files
=====

   * GNU Pascal no built-in `Assign' procedure for files, but you can
     write it by yourself using the "Bind" mechanism of Extended Pascal:

            Procedure Assign ( Var T: Text; Name: String );

            Var
              B: BindingType;

            begin (* Assign *)
              unbind ( T );
              B:= binding ( T );
              B.Name:= Name;
              bind ( T, B );
              B:= binding ( T );
            end (* Assign *);

   * GNU Pascal has no untyped files, "BlockRead", or "BlockWrite".


File: ^.!gcc.docs.pascal.gpc,  Node: Built-in constants,  Next: Built-in operators,  Prev: Files,  Up: Borland Pascal

Built-in constants
==================

   * Pi constant:  not built-in.  Use Pi = 3.14159265358979323846.

   * Other built-in constants:  GNU Pascal has `MaxInt', `MaxChar',
     `MaxReal', and `MinReal', but no `MaxLongInt'.


File: ^.!gcc.docs.pascal.gpc,  Node: Built-in operators,  Next: Built-in Procedures and Functions,  Prev: Built-in constants,  Up: Borland Pascal

Built-in operators
==================

   * Exponentiation:  According to Extended Pascal, GNU Pascal supports
     exponentiation operators `pow' and `**' which do not exist in
     Borland Pascal.  You can use `x pow y' for integer and `x ** y'
     for real or complex exponents; the basis may be integer, real or
     complex in both cases.

   * Address operator: GNU Pascal accepts Borland's `@', but also `&'
     as an address operator.

   * GNU Pascal has a symmetric set difference operator `set1 >< set2'.
     See *Note Extensions:: for more about this.


File: ^.!gcc.docs.pascal.gpc,  Node: Built-in Procedures and Functions,  Next: Parameters,  Prev: Built-in operators,  Up: Borland Pascal

Built-in Procedures and Functions
=================================

   * `Write' and `writeln' default behaviour:  The numeric default
     format of "write" and "writeln" differs between both Pascal
     dialects.  The standard format of GNU Pascal is a field of length
     14 for real, and a field of length 10 for integer values, while
     Borland Pascal begins just left by default.  An explicit
     fieldlength of zero causes GNU Pascal to omit the output; in
     Borland Pascal it yields the default.

   * `GetMem' and `FreeMem':  `GetMem' can also act as a function in
     GNU Pascal:

            p:= GetMem ( 1024 );

     The second parameter to FreeMem is ignored by GNU Pascal and may
     be omitted.  Memory blocks are always freed with the same size
     they were allocated with.

     Remark:  Extended Pascal Schema types will provide a cleaner
     approach to most of the applications of `GetMem' and `FreeMem' in
     the future.

   * `Min' and `max':  GNU Pascal has built-in `min' and `max'
     functions (two arguments) which work for all ordinal types
     (`Integer', `Char', ...) plus `Real'.

   * `UpCase' function:  not built-in.

   * `Lo', `Hi', `Swap' functions:  not built-in.


File: ^.!gcc.docs.pascal.gpc,  Node: Parameters,  Next: Miscellaneous,  Prev: Built-in Procedures and Functions,  Up: Borland Pascal

Parameters
==========

   * Untyped Var parameters are denoted by

            Procedure Foo ( Var x: Void );

     in GNU Pascal instead of

            Procedure Foo ( Var x );

     in Borland Pascal.

   * GNU Pascal defines "ellipsis" parameters vor variable argument
     lists,

            Procedure Foo ( a: Integer; ... );

     but does not (yet) provide a portable mechanism to access the
     additional arguments.

   * Structured function return values:  According to Extended Pascal,
     GNU Pascal allows structured function return values.

   * Open array parameters are partially implemented:  They work, but a
     warning is given. However, Standard Pascal conformant array
     parameters (also partially implemented) are a "cleaner" mechanism
     to pass arrays of variable size.

   * GNU Pascal supports Standard Pascal's procedural parameters:

            Procedure DrawGraph ( f: Function ( Real ): Real );


File: ^.!gcc.docs.pascal.gpc,  Node: Miscellaneous,  Prev: Parameters,  Up: Borland Pascal

Miscellaneous
=============

   * Headlines:  According to Extended Pascal, a Program headline must
     contain the program's parameters:

              Program Foo ( Input, Output );

     In GNU Pascal, headline parameters are optional.  If the headline
     is omitted, a warning is given.

   * Case statements:  In a case statement, GNU Pascal has `otherwise'
     instead of `else' (according to Extended Pascal):

            case x of
              1: writeln ( 'one' );
              2: writeln ( 'two' );
              otherwise: writeln ( 'many' );
            end (* case *);

     If there are two ore more statements following `otherwise', they
     must be grouped with `begin' and `end'.

   * Char constants: Chars like `#13' or `^M' are not implemented into
     GNU Pascal.

   * Sets: GNU Pascal has a `card ( myset )' function for sets which
     counts their elements.

   * Inline:  GNU Pasccal allows "inline" Procedures and Functions,
     while Borland Pascal only allows machine code to be inline:

     Borland Pascal:

            Function Max ( x, y: Integer ): Integer;
            Inline ( $58 / $59 / $3B / $C1 / $7F / $01 / $91 );

     GNU Pascal:

            Inline Function Max ( x, y: Integer ): Integer;

            begin (* Max *)
              if x > y then
                Max:= x
              else
                Max:= y;
            end (* Max *);

     (Actually, a more general Max is already built-in.)

     This feature is not so important as it might seem because in
     optimization level 3 (see above), GNU Pascal automatically
     "inlines" short Procedures and Functions.


File: ^.!gcc.docs.pascal.gpc,  Node: GPC Bugs,  Next: How to Contribute,  Prev: FPK Pascal,  Up: Top

Known bugs and how to report bugs
*********************************

   If you encounter a bug with GPC, please check whether it is one of
the known bugs.  If not, report it to the GNU Pascal mailing list
`[e-mail]'.  (But always report it if you solve the problem! ;-)

Known bugs
==========

   The GPC compiler does not yet implement the whole ISO 7185 Pascal
standard, so please take this into account when you consider using this
for any purpose.

   See the file `version.c' to find out the version number of this GPC
(or run `gpc -v')

   Problems in this GPC version:

   * High optimization levels do not work properly on the Alpha.  Some
     conformance tests FAIL when compiled with -O6 flag, which means
     that the compiler generates invalid code. Don't use this flag in
     the alpha before the problem gets fixed.  It might have something
     to do with automatic inlining, but I have not yet looked at this.
     -O flag should be ok.  (Also take care when using explicit inline
     functions)

   * For some reason the pascal main program does not get lineno stabs
     -> It is hard to debug it with gdb...

   * The modules export everything, not just the stuff in the export
     interfaces. However, the unexported variables and functions are
     invisible to modules in other files.

   * type checking is mostly what C does, not what Pascal requires, so
     GPC does not yet implement a strongly typed language.  Although
     correct programs compile, incorrect ones compile also.

   * run time errors are not checked.

   * the inline set operations have some problems with operations on
     two sets if the sets do not contain equally many segments.

   * In addition, the set code generated in the alpha causes runtime
     runtime errors in the generated code.

   * Conformant arrays don't yet work (in general).  Until they do,
     this is a LEVEL-0 compiler.

Inconveniences
==============

   * NEW & DISPOSE optional tag field arguments are ignored (warning
     given, code works)

   * GDB does not yet understand pascal sets, files or subranges.  Now
     GDB allows you to debug these things, even though it does not yet
     understand some stabs.

   * PACKED does not pack. (implementation dependent, warning given,
     code works)

   * Files of integer subranges that would fit in a byte do not;
     instead they are handled as files of integer.  This is especially
     annoying with "file of 0..255".

Notes for debugging
===================

   * Forward referencing pointers generate DBX style debugging symbols
     by outputting the `.stabs' as an unknown pointer and later it just
     outputs the same `.stabs' again, but this time it also tells what
     type the pointer points to.  This seems to work for gdb. As of
     this writing I have not checked what happens with SDB type
     debugging info.  It might be that the pointer is left to be a
     `(void *)' pointer, so you have to cast it in order to output the
     object the pointer points to.

     Also, I have not tried any other debugger than gdb.  If you do,
     please let me know what happens.

     I think that GDB does not yet support the kind of `.stabs' that
     should be used to do this correctly:

            .stabs ":tANUMBER=BNUMBER", WHATEVER

     where ANUMBER is the unknown pointer type referenced earlier, and
     the BNUMBER is the type which ANUMBER actually is. This construct
     is not required in C.

   * When debugging, please note that the Initial Letter In Each
     Identifier Is In Upper Case And The Rest Are In Lower Case. If
     you wish to call C-routines declare them with the "C" directive,
     as follows:

          Procedure FooBAR(i:integer);c;

     This makes the external name to be `_foobar' (replace `_' with you
     machine prefix.)

          Procedure FooBAR(i:Integer); External;

     Uses external name `_Foobar'.

     It is done like this to reduce name clashes with `libc.a' and
     other possible libraries.

   * All visible GPC runtime system library routines are named `_p_...'.

   * However, the main program name is not capitalized.  (this is a
     kludge -> it may now clash with libc  identifiers. We'll change
     this somehow later)


File: ^.!gcc.docs.pascal.gpc,  Node: How to Contribute,  Next: Index,  Prev: GPC Bugs,  Up: Top

How *you* can contribute to GNU Pascal
**************************************

   Below you can find a list of jobs which should be done for
GNU-Pascal.  In cases where somebody is already working on it, the name
of that person is written behind the job's description together with
the status of the project; e-mail addresses are given below.

   If there is already a name behind a job, 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.

   Welcome to the GNU Pascal development team!

List of jobs
============

     Overall coordination                    Juki                works ;-)
     Coordination with GCC developers        Juki                 ?
     Merge into GCC main distribution        Juki                 ?

     ISO 7185 Standard Pascal                Juki                works
     ISO 10206 Extended Pascal               Juki                90%
     Object Pascal                            ?
     Borland Pascal 7.0                      Peter               80%
     Delphi                                   ?
     Pascal-SC                               Peter               please help!
     Compiler options to force one standard  Peter               planned

     EMX version (DOS and OS/2)              Peter               works
     Linux binaries                          Peter               works
     DJ version (DOS)                        JanJaap             works
     Win32 version                           JanJaap             70%
     Cross compilers Linux -> others         JanJaap             works

     Installation instructions               Larry                ?
     Documentation                           Larry                ?

     Type checking                           Juki                 ?
     Automatic make                          Peter               works
     Objects: C++ code compatibility          ?
     PXSC module syntax                      Peter               planned
     Procedure overloading                   Peter               planned
     Precompiled module interfaces           Peter               works

     Run time system                         Juki                works
     I/O error handling                       ?
     Turbo compatible DOS, CRT, Graph, ...    ?                  ask Peter
     Turbo Vision compatible library          ?
     POSIX library (replacement for DOS)     Berend              to be ported
     Replacement for (parts of) CRT          Peter               beta (BO5)
     Replacement for Graph                   Peter               planned (BO5)
     Replacement for Turbo Vision            Peter               planned (BO5)

     Port of the RHIDE IDE                   JanJaap              ?
     Improvement of the XWPE IDE              ?

List of contributors (in alphabetical order)
============================================

     Berend              Berend de Boer, Nederlands
                         <[e-mail]>

     JanJaap             Jan Jaap van der Heijden, Nederlands
                         <[e-mail]>

     Juki                Jukka Virtanen, Finland
                         <[e-mail]>

     Larry               Larry Carter, USA
                         <[e-mail]>

     Peter               Peter Gerwinski, Germany
                         <[e-mail]>


File: ^.!gcc.docs.pascal.gpc,  Node: FPK Pascal,  Next: GPC Bugs,  Prev: Borland Pascal,  Up: Top

FPK Pascal and GNU Pascal--a comparision
****************************************

   by Florian Klaempfl <[e-mail]>
and Peter Gerwinski <[e-mail]>
7. July 1996

                  FPK Pascal                       GNU Pascal
                  ----------                       ----------

     aim:         free Borland compatible          free portable
                  32-bit Pascal compiler           32-bit Pascal compiler

     version:     0.6.4                            2.6.3

     operating    DOS (DJ), OS/2                   DOS, OS/2 (EMX)
     systems:                                      DOS (DJ)
                                                   arbitrary UNIX systems

     written in:  Pascal, TP Syntax                C
                  (compiles itself)

     source:      900 kB                           2.8 MB
                                                   plus source of GCC (8 MB)

     language     Borland Pascal 7.0,              ISO 7185, ISO 10206,
     standard:    (parts of) Delphi II             (most of) Borland Pascal 7.0

     extensions:  function overloading             operators

     home server: http://www.brain.uni-freiburg.de ftp://kampi.hut.fi/jtv/gnu-pascal

     license:     FreeWare (GPL)                   FreeWare (GPL)

     author:      Florian Klaempfl, Germany        Jukka Virtanen, Finland
                  [e-mail]   [e-mail]


File: ^.!gcc.docs.pascal.gpc,  Node: Index,  Prev: How to Contribute,  Up: Top

Index
*****

* Menu:

* -lgcc, use with -nodefaultlibs:       Link Options.
* -lgcc, use with -nostdlib:            Link Options.
* -nodefaultlibs and unresolved references: Link Options.
* -nostdlib and unresolved references:  Link Options.
* gprof:                                Debugging Options.
* longjmp warnings:                     Warning Options.
* prof:                                 Debugging Options.
* tcov:                                 Debugging Options.
* stdarg.h and RT PC:                   RT Options.
* varargs.h and RT PC:                  RT Options.
* Alpha OSF/1:                          Alpha OSF/1.
* AMD29K options:                       AMD29K Options.
* arguments in frame (88k):             M88K Options.
* ARM options:                          ARM Options.
* assembler syntax, 88k:                M88K Options.
* Bison parser generator:               UNIX.
* bit shift overflow (88k):             M88K Options.
* byte writes (29k):                    AMD29K Options.
* code generation conventions:          Code Gen Options.
* command options:                      Invoking GPC.
* compiler version, specifying:         Target Options.
* COMPILER_PATH:                        Environment Variables.
* configuration dependent notes:        UNIX.
* contributors:                         Contributors.
* Convex options:                       Convex Options.
* CPLUS_INCLUDE_PATH:                   Environment Variables.
* cross compiling:                      Target Options.
* cross-compiler:                       Cross-Compiler.
* C_INCLUDE_PATH:                       Environment Variables.
* debugging information options:        Debugging Options.
* debugging, 88k OCS:                   M88K Options.
* dependencies for make as output:      Environment Variables.
* dependencies, make:                   Preprocessor Options.
* DEPENDENCIES_OUTPUT:                  Environment Variables.
* dialect options:                      Pascal Dialect Options.
* directory options:                    Directory Options.
* divide instruction, 88k:              M88K Options.
* djgpp:                                DJGPP.
* DW bit (29k):                         AMD29K Options.
* EMX:                                  EMX.
* environment variables:                Environment Variables.
* file name suffix:                     Overall Options.
* file names:                           Link Options.
* global offset table:                  Code Gen Options.
* GNU Pascal command options:           Invoking GPC.
* gp-relative references (MIPS):        MIPS Options.
* GPC_EXEC_PREFIX:                      Environment Variables.
* grouping options:                     Invoking GPC.
* hardware models and configurations, specifying: Submodel Options.
* HPPA Options:                         HPPA Options.
* i386 Options:                         i386 Options.
* IBM RS/6000 and PowerPC Options:      RS/6000 and PowerPC Options.
* IBM RT options:                       RT Options.
* identifying source, compiler (88k):   M88K Options.
* installing GNU Pascal:                Installation.
* Intel 386 Options:                    i386 Options.
* kernel and user registers (29k):      AMD29K Options.
* language dialect options:             Pascal Dialect Options.
* large bit shifts (88k):               M88K Options.
* Libraries:                            Link Options.
* LIBRARY_PATH:                         Environment Variables.
* link options:                         Link Options.
* Linux:                                System V.
* M680x0 options:                       M680x0 Options.
* M88k options:                         M88K Options.
* machine dependent options:            Submodel Options.
* make:                                 Preprocessor Options.
* memory model (29k):                   AMD29K Options.
* messages, warning:                    Warning Options.
* MIPS options:                         MIPS Options.
* MS-DOS <1>:                           EMX.
* MS-DOS:                               DJGPP.
* OBJC_INCLUDE_PATH:                    Environment Variables.
* OCS (88k):                            M88K Options.
* optimize options:                     Optimize Options.
* options to control warnings:          Warning Options.
* options, code generation:             Code Gen Options.
* options, debugging:                   Debugging Options.
* options, dialect:                     Pascal Dialect Options.
* options, directory search:            Directory Options.
* options, GNU Pascal command:          Invoking GPC.
* options, grouping:                    Invoking GPC.
* options, linking:                     Link Options.
* options, optimization:                Optimize Options.
* options, order:                       Invoking GPC.
* options, preprocessor:                Preprocessor Options.
* order of options:                     Invoking GPC.
* OS/2:                                 EMX.
* output file option:                   Overall Options.
* overloaded virtual fn, warning:       Warning Options.
* parser generator, Bison:              UNIX.
* PIC:                                  Code Gen Options.
* preprocessor options:                 Preprocessor Options.
* processor selection (29k):            AMD29K Options.
* r0-relative references (88k):         M88K Options.
* register positions in frame (88k):    M88K Options.
* RS/6000 and PowerPC Options:          RS/6000 and PowerPC Options.
* RT options:                           RT Options.
* run-time options:                     Code Gen Options.
* search path:                          Directory Options.
* second include path:                  Preprocessor Options.
* sequential consistency on 88k:        M88K Options.
* smaller data references (88k):        M88K Options.
* smaller data references (MIPS):       MIPS Options.
* SPARC options:                        SPARC Options.
* specifying compiler version and target machine: Target Options.
* specifying hardware config:           Submodel Options.
* specifying machine version:           Target Options.
* stack checks (29k):                   AMD29K Options.
* storem bug (29k):                     AMD29K Options.
* structure passing (88k):              M88K Options.
* submodel options:                     Submodel Options.
* suppressing warnings:                 Warning Options.
* SVr4:                                 M88K Options.
* syntax checking:                      Warning Options.
* synthesized methods, warning:         Warning Options.
* System V:                             System V.
* target machine, specifying:           Target Options.
* target options:                       Target Options.
* TMPDIR:                               Environment Variables.
* underscores, avoiding (88k):          M88K Options.
* unresolved references and -nodefaultlibs: Link Options.
* unresolved references and -nostdlib:  Link Options.
* VAX options:                          VAX Options.
* warning for overloaded virtual fn:    Warning Options.
* warning for synthesized methods:      Warning Options.
* warning messages:                     Warning Options.
* Win32:                                Win32.
* Windows 95:                           Win32.
* Windows NT:                           Win32.
* zero division on 88k:                 M88K Options.



Tag Table:
Node: Top1261
Node: Copying2768
Node: Contributors21964
Node: Funding26480
Node: Look and Feel28991
Node: Manifesto36369
Node: Purpose62413
Node: Installation63698
Node: UNIX65429
Node: System V72956
Node: Alpha OSF/173771
Node: DJGPP74650
Node: EMX75274
Node: Win3277785
Node: Cross-Compiler78852
Node: Steps of Cross80601
Node: Configure Cross81736
Node: Build Cross82824
Node: Invoking GPC83421
Node: Option Summary86314
Node: Overall Options96707
Node: Pascal Dialect Options101622
Node: Code Gen Options103520
Node: Warning Options111575
Node: Debugging Options125855
Node: Optimize Options135478
Node: Preprocessor Options145843
Node: Assembler Options152399
Node: Link Options152780
Node: Directory Options157865
Node: Target Options161371
Node: Submodel Options165083
Node: M680x0 Options166292
Node: VAX Options169815
Node: SPARC Options170364
Node: Convex Options176810
Node: AMD29K Options179005
Node: ARM Options182054
Node: M88K Options183485
Node: RS/6000 and PowerPC Options191487
Node: RT Options202512
Node: MIPS Options204230
Node: i386 Options211693
Node: HPPA Options217102
Node: Intel 960 Options220216
Node: DEC Alpha Options222840
Node: Clipper Options224526
Node: H8/300 Options224939
Node: System V Options225398
Node: Environment Variables226098
Node: Keywords230332
Node: Built-in235582
Node: Extensions238951
Node: Extended Pascal288189
Node: Borland Pascal300800
Node: Borland compatibility301656
Node: There is no IDE!302395
Node: Comments and compiler directives306033
Node: Units; GPI files and AutoMake309173
Node: Optimization312409
Node: Debugging313298
Node: GPC inline assembler314363
Node: Objects315876
Node: Strings316384
Node: Typed constants317637
Node: Bit; byte and memory manipulation318569
Node: User-defined operators319843
Node: Data types321018
Node: Files322868
Node: Built-in constants323549
Node: Built-in operators323898
Node: Built-in Procedures and Functions324615
Node: Parameters325977
Node: Miscellaneous327051
Node: GPC Bugs328789
Node: How to Contribute333135
Node: FPK Pascal336760
Node: Index338372

End Tag Table