-----------------------------------------------------------------------------
    Copyright (C) 2023 Jorge Giner Cordero
    This file is part of bas55 (ECMA-55 Minimal BASIC System).
    bas55 license: GNU GPL v3 or later.
-----------------------------------------------------------------------------

bas55 - ECMA-55 Minimal BASIC System
====================================

`bas55` is an implementation of the *Minimal BASIC* programming language as
described by the ECMA-55 standard [1]. bas55 provides an interpreter and an
editor with line renumbering capabilities.

[1]: https://www.ecma-international.org/publications-and-standards/standards/ecma-55/

bas55 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 3 of the License, or (at your option) any later
version.

bas55 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
bas55.  If not, see <https://www.gnu.org/licenses/> .

Home page: https://jorgicor.niobe.org/bas55  
GitHub: https://github.com/jorgicor/bas55  
Send bug reports to: jorge.giner@hotmail.com

Windows precompiled binaries
============================

A precompiled distribution for *Microsoft Windows* is provided in a ZIP file.
It can be found at https://jorgicor.niobe.org/bas55 . After decompressing it,
you will have these files:

~~~
bas55.exe       The program.
bas55.html      The manual.
readme.txt      This file.
copying.txt     License.
news.txt        What's new in this version.
data/*.BAS      Several programs and games.
data/readme.txt Description of the programs included.
~~~

Double-click `bas55.exe` or open a system console and go to the folder where
you have decompressed the ZIP file and type `bas55`. Then type `HELP` to
see a list of available commands.  Double-click `bas55.html` to see the
program documentation in your web browser.

Compiling
=========

Getting the code from revision control
--------------------------------------

If you cloned the project from a revision control system (i.e. GitHub), you
will need first to use the GNU autotools to generate some files, in particular,
the `configure` script. Use:

    $ ./bootstrap

to generate the required files. You will need *GNU autoconf*, *GNU automake*,
*GNU texinfo*, *help2man*, and a *yacc* parser (tested only with *GNU bison*).

Compiling from the source distribution
--------------------------------------

If you have the official source package, and you are building on a Unix-like
environment (this includes *Cygwin* on *Windows*), you can find generic
instructions in the file `INSTALL`. The complete source distribution can
always be found at https://jorgicor.niobe.org/bas55 .  

After installing, you can type `man bas55` to see a brief explanation on how to
use the `bas55` program.  More detailed documentation, including a tutorial on
the *Minimal BASIC* programming language, can be found using the GNU
documentation system: type `info bas55` to read it.

Normally, after installing from source, you can find this on your system:

~~~
/usr/local/bin/bas55                    The program executable.
/usr/local/share/man/man1/bas55.1       The manual page.
/usr/local/share/info/bas55.info        The info manual.
/usr/local/share/doc/bas55/COPYING      License.
/usr/local/share/doc/bas55/README       This file.
/usr/local/share/doc/bas55/NEWS         What's new in this version.
/usr/local/share/doc/bas55/INSTALL      How to compile, install and uninstall.
/usr/local/share/doc/bas55/AUTHORS      Authors.
/usr/local/share/bas55/*.BAS            Several programs and games.
/usr/local/share/bas55/README           Description of the programs included.
~~~

If you are installing bas55 using your OS distribution package system, these
folders will probably be different.  Try changing `/usr/local` to `/usr`.

Enhanced editing capabilities on GNU/Linux or *BSD
--------------------------------------------------

On GNU/Linux or BSD systems, you can have some editing enhancements while
`bas55` is in editor mode, like a history of previous typed lines, command
autocompletion, direct access to a line by its number to edit it, etc.

You will need the GNU Readline library (recommended) or the NetBSD Editline
library (libedit) installed on your system. 

NetBSD's libedit, as of this writing, has some compatibility issues when used
in readline emulation mode.  I recommend GNU Readline even if you are on a BSD
system, or at least try both.

So, to compile with GNU Readline support, you can pass `--with-readline` to the
configure script, and it will try to detect the library.

To compile with libedit support, you can pass `--with-libedit` to the
configure script to detect the library. Sometimes, the library is already
linked with its dependencies and you don't need to do anything else, but
sometimes it is not. In this case, you have to link also with one the termcap,
curses or ncurses libraries. For this, you have the options `--with-termcap`,
`--with-curses` and `--with-ncurses`. This means that if using
`--with-libedit` gives you an error but you know that libedit is installed,
try combining this option with one of the others.

These are some tests I did:

* Slackware Linux 14.2 with the SlackBuild libedit 3.1 installed:
 `--with-libedit` is enough.
* FreeBSD 11.1: `--with-libedit` is enough.
* NetBSD 7.1.1: `--with-libedit` is enough.
* OpenBSD 6.2: `--with-libedit --with-curses` (or `--with-termcap`) is needed.

