Iron Spring PL/I Compiler

Linux Version 1.1.0
20 Jun 2023

Release Notes

Introduction

This document provides information on using the Iron Spring PL/I compiler and compiled programs on the Linux platform. For information on the OS/2 platform, see the corresponding document
readme_os2.

The current version still contains bugs. You can help improve the compiler. See the section Reporting bugs.

Trademarks
ArcaOS is a trademark of Arca Noae.
Gnu is a trademark of the Free Software Foundation.
IBM is a trademark of IBM, Inc.
Intel is a trademark of Intel Corporation.
Iron Spring is a trademark of Iron Spring Software.
Linux is a registered trademark of Linus Torvalds.
VAX is a trademark of Hewlett-Packard, Inc.
WATCOM is a trademark of Sybase, Inc. and its subsidiaries.
Library heap manager based on code Copyright (c) 2001-2006 Wolfram Gloger.

License

<boring-legal-stuff>
This license a legal agreement between you and Iron Spring Software. Your use of this software signifies that you agree to the terms of this license.

Iron Spring Software grants you the right to use and copy the Iron Spring PL/I compiler and library freely. You may distribute programs compiled using the compiler and/or linked with the library under any terms you wish without restriction. The source to the library is licensed under the terms of the Gnu Lesser General Public License (LGPL).

All material is copyright Iron Spring Software, 2023.

THE COMPILER AND LIBRARY ARE PROVIDED "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 COMPILER AND LIBRARY IS WITH YOU. SHOULD THEY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
</boring-legal-stuff>

Contents

This distribution includes the executable for the PL/I compiler plic, the static library lib/static/libprf.a, and the sources for the library and sample programs.

  pli-1.1.0
    |
    +-----------------------samples----------------lib
    |                          |                    |
 plic                       (Sample sources and     +--------------------------static---include----source-----------alt
 (compiler executable)       %include files,                                   |         |         |                 | 
 (documentation, etc.)       sample makefiles                                  |         |         +--------asm      |
                             and module definition                             |         |   (PL/I source)   |     (alt storage   
                             file).                                            |         |               (assembler management)
                                                                               |  (%include files          source)
                                                                               |    required by                                                                                      
                                                                               |     library).
                                                                               |
                                                                     libprf.a (static library)

Requirements

The folowing software is required to run the Linux version of the compiler:
The following software is recommended:

Restrictions

Version 1.1.0 has a number of restrictions. The most significant are:

Installation

  1. The distribution file is supplied as a gzipped tar file. Unpacking it will create a directory named "pli-1.1.0".
  2. Only the compiler (pli-1.1.0/plic) and the static runtime library (pli-1.1.0/lib/libprf.a) are required.
  3. Move the compiler to a directory in your $PATH such as /usr/bin, and move libprf.a to a directory such as /usr/lib. Alternatatively, you can specify which directory the library is in in your makefiles.
    An installation procedure is provided. cd to the 'pli-1.1.0' directory and type 'make install' (with suitable authority). This procedure moves the compiler to '/usr/bin' and creates a symlink 'plic' referencing it, and moves the library to '/usr/lib' and creates the symlink 'libprf.a'.

A later version will be installable using one or more of the standard package managers.

Sample Programs

The file samples/samples.html contains instructions and a list of all the sample programs. The comments in each program contain information on using the program.
  1. Test the sample programs. In this release only static linking is supported. CD to the directory "pli-1.1.0/samples" and type "make -f Makefile.Linux" without the quotes, case is significant.. The sample programs "numwrd", "filedump", "libver", "print_listing", and "task" build to executables, the remainder should generate object files.
  2. Test numwrd. Enter "./numwrd 123". The program should display the result "one hundred twenty-three".
  3. You might want access to the %INCLUDE files in "pli-1.1.0/lib/include" or "pli-1.1.0/samples" for your own programming.

Using the compiler

The "samples" directory contains three sample makefiles that can be used to compile and link PL/I programs. You should copy these and modify them for your requirements. "LC_make" and "LCC_make" both use gcc to drive the linker; the program entry will be libc's "_start". "SA_make" calls ld directly and should be used only for programs that don't call any C functions. The program entry will be PL/I's "main". In all cases the static PL/I runtime linkary "libprf.a" is required, indicated by "-lprf" in the linker command.

The Iron Spring PL/I Compiler Programming Guide describes the PL/I compiler options available.

Linking PL/I programs

The following examples show different methods of linking PL/I programs.

This command uses gcc to link a PL/I program with libc, and use C's malloc and free for heap storage management.
gcc -o ${EXE} ${OBJ} ${ALTDIR}/fhs.o ${ALTDIR}/ghs.o -lprf -Wl,-M >${MAP}

This command uses gcc to link a PL/I program with libc, and use PL/I's heap storage management.
gcc -o ${EXE} ${OBJ} -lprf -Wl,-M >${MAP}

This command uses ld to link a standalone PL/I program with no reference to libc.
ld -z muldefs -Bstatic -M -e main -t -o ${EXE} \ ${OBJ} \ -lprf \ >${MAP}

64-bit Linux Considerations

The Iron Spring PL/I compiler, and compiled PL/I programs, will run on a 64-bit system as 32-bit applications. The following steps are required:

Documentation

The
Iron Spring PL/I Compiler Programming Guide contains a description of the features of the compiler. Except as noted in the Programming Guide under Compiler Differences and Restrictions this compiler is compatible with the IBM "PL/I for MVS and VM Compiler 1.1". A complete language reference will be available as part of a future release.

Documentation for the IBM compiler is available online at teampli.net.

Changes