1. Introduction

1.1 Copying
1.2 Installing RHIDE
1.3 What is RHIDE?
1.4 Requirements
1.5 Getting started
1.6 The program GPR2MAK
1.7 The program GPREXP
1.8 First steps with RHIDE
1.9 Environment variables

1.1 Copying

RHIDE is copyright by Robert Höhne. Parts of RHIDE are copyright by other people as noted in the source files.

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.

additional permission:

As a special additional permission, the library librhuti which is in the source tree of the RHIDE sources in the librhuti/ subdirectory can be distributed alone freely without any restrictions. It is not limited to use under the terms of the GPL or LGPL. For more information see the file COPYING.RHU in that subdirectory.

Non-binding request

If you distribute RHIDE together with other products it would be nice, if you could give me a note about it so I'll be informed. Of course you can send me a copy of the distribution medium but this is not required.

For contacting the author send electronic mail to

robert.hoehne@gmx.net

or paper mail to

Robert Höhne Am Berg 3 D - 09573 Dittmannsdorf Germany

1.2 Installing RHIDE

There are two archives

`rhide??b.zip'

This contains the executables and the documentation for RHIDE running on DJGPP

`rhide-?.?-1.i386.rpm'

This is a RPM package with the binaries of RHIDE for GNU/Linux. (currently they are built on SuSE 8.0)

`rhide??s.zip'

This contains the sources of RHIDE for DJGPP.

`rhide-?.?-1.src.rpm'

This is a RPM package with the sources of RHIDE for GNU/Linux.

NOTE: The sources for the GNU/Linux and DJGPP versions are of course in its core the same, there are only differences in the directory structure and maybe in some preconfigured files. But in general both archives can be used on both systems (after some cosmetic changes).

where `??' in the above filenames stand for the digits of the actual version of RHIDE which is as of writing this version 1.5 which leads to `15'.

These archives can be found at
The RHIDE home page
or at any ftp site, which mirrors DJGPP. On that DJGPP mirrors are of course only the DJGPP archives available.

RHIDE is now also hosted on sourceforge, from where you can download also the latest versions.
RHIDE on sourceforge

To install these archives, unzip them in the DJGPP-root directory, like any other DJGPP package.

To install the GNU/Linux RPM packages, use your favorite install program (most Linux distributions allow to install RPM packages) or install it with the Redhat package manager itself.

1.3 What is RHIDE?

What is RHIDE? RHIDE is an Integrated Development Environment for compiling C- or C++-files (GNU-Assembler source files also supported) in an environment, which has an integrated editor where you can edit your source files and a project management, where you can define, which files are needed to build a program or a library.

For what stands the name RHIDE? This has nothing mystic in it. It comes simply from my initials RH and IDE (Integrated Development Environment).

RHIDE works like the IDE from Borland, which comes with Turbo C++ 3.1 and is written with the Turbo Vision library, which I have ported to use with DJGPP. Features of this IDE are:

• Syntax highlighting is now supported and you can customize all colors on your desktop.

• You can redirect the stdout and stderr from your program to a window in the IDE.

• You can generate a makefile for your project, so you can build the program also without the IDE.

• Most of the commandline options of GCC can be customized.

• You can also build a library instead of an executable.

• When saving a file to disk, the modification time of this file will be set to the time of the last modification in the editor.

• You can interrupt external programs (the compilers or your program) by pressing Ctrl+C or Ctrl+Break which are ignored by the IDE. That means also, that you cannot interrupt the IDE by pressing these keys. If you want to enable this, compile the IDE without the `-DNO_BREAK'-flag.

• The integrated debugger. You can debug your program within RHIDE by executing each source line of your code and evaluating/modifying variables and expressions.

• You can define another compiler to compile your source files.

In addition to RHIDE I have included a stand-alone debugger (called `rhgdb.exe'), which is GDB 5.0 with a Turbo Vision user interface.

1.4 Requirements

RHIDE works under and is compiled with DJGPP V2. To compile your programs you need a working GCC-configuration, that means, GCC must be found in your path. Because DJGPP works only under DPMI you need a DPMI-Server. If you run it under Windows 3.1(1)/95, you have DPMI. Under MS-DOS you need either a memory-manager, which give you DPMI-services (I think QEMM is it, EMM386 has no DPMI-support), or you use CWSDPMI, the free DPMI-server from Charles W. Sandmann, which you can find on SimTel-ftp-sites. I use it and it works fine for me.

Running RHIDE under Windows NT or Windows 2000 should work, since I have W2000 and developing there.

The builtin editor uses a simple heuristic to check, if a file is in UNIX or DOS text format. It checks the first 1024 Bytes, and if there is a lf without a cr, all lf's will be translated to cr/lf's. This is done at first only in memory. But if you save your file to disk, it will be saved in DOS text format.

RHIDE will work correctly only with DJGPP version 2.03 or higher and please if you are running under W2000 (or XP) get always the latest DJGPP, since there are many efforts to make DJGPP working on these systems.

1.5 Getting started

To run RHIDE type

rhide [options] ['file-name']

or

rhide [options] 'project-name' [options]

Here stands 'file-name', for a file, which you want to open at start up. If it has no suffix it is assumed to be a 'project-name'.

'project-name' stands for a name of your project. If you don't type it, RHIDE searches the current directory for a project file. If there exists only one, it will be opened. If there exist more than one or none, RHIDE will not open a project, you have to do it manually. see section 3.8.1 Open project.

Possible options are for debugging RHIDE itself see section 1.5.2 Debugging RHIDE. If no project was open, you will see an empty desktop. At the top-line of the screen you can see the menu. This is activated by pressing F10 or by clicking with the mouse at this line. Alternatively you can press Alt plus the highlighted character of a pull-down menu, e.g. to activate the File menu, press Alt+F. At the bottom is the status line with some hotkeys and their functions displayed.

Other options are:

`-H'

Do not install the console switch handler, which saves/restores the modified keyboard layout. This options works only when running under GNU/Linux.

`-S'

Tells RHIDE to use only 16bit access to the video memory under DJGPP, because some video cards cannot handle the 32bit access.

`-E'

Dump all variables known to RHIDE (the builtins and the real environment variables) to stderr end exit.

`-C'

Disable the handling of SIGINT

`-y'

Use long filenames (only under Windows 95)

`-n'

Do not use long filenames (only under Windows 95)

`-c'

Do not convert the case of any file name

`-h'

Show a short help about all the possible options.

`-b'

Use BIOS calls for setting and resetting the behavior of the 7th bit in a color attribute (blinking or 16 background colors) instead of direct outputs to the VGA registers.

`-p'

Normally RHIDE converts all the num-pad keys to the equivalent keys on the other keyboard (of course also by checking the NumLock key). With this switch you can disable this.

`-G n'

Select which method is used for swapping the display. Currently there are two, little different functions implemented. If you have problems with display swapping when in graphics mode, try to use another method and see if that helps.

`-K'

Tell RHIDE, to use real BIOS calls for it's keyboard input. This is needed sometimes, when you have installed some special keyboard drivers.

`-M'

This tells RHIDE to not to install the mouse callback function for getting the mouse events. Instead of this RHIDE calls the mouse BIOS functions for getting any event of the mouse. This option should be used mainly when running under Windows NT (but there I select this now automatically by default)

At the upper right corner of the screen you can see the free virtual/physical memory (where M stands for Megabytes, K for Kilobytes and B for Bytes), if enabled see section 3.9.6.3 Preferences.

If you try to open a project, which does not exist, RHIDE will create a new one. For the default setting in the newly created project, RHIDE will look first in some directories if there exists an options file for RHIDE called `rh_opt.gpr'. If this file is found, the options from that file are used for the new project, otherwise the in RHIDE hardcoded defaults are used.

1.5.1 Supported languages
1.5.2 Debugging RHIDE

1.5.1 Supported languages

There is also support for multiple languages. For this RHIDE uses the GNU gettext library. With this lib it is possible to support multiple languages without changing any code of RHIDE, when adding a new language.

There are two ways for selecting the language. Either you set the environment variable LANGUAGE to the language you want or give it as a commandline argument to RHIDE. The normal way is by setting LANGUAGE. If you have installed RHIDE as described in the `readme', you should specify the language with a two character shortcut. Because of my limited time, the translations to are not synronized with RHIDE.

When you want to specify the language on the commandline, use the following syntax:

rhide -L LANGUAGE

where LANGUAGE represents the language code.

If you do not specify any language, English is assumed.

Because it was not possible to get all the translations at the time when RHIDE was ready, I included only the message files (that are the files with the `.mo' suffix) as they are ready in the binary archive. That means that it is possible that you will see some strings in English instead of your language.

1.5.2 Debugging RHIDE

I have added some commandline options to debug the IDE itself. These options are the following:

`-dt'

Do not remove the temporary files which the IDE creates. The names of these files will be printed to stderr.

`-dc'

Print to stderr the commands which the IDE executes.

`-dd'

Print to stderr how the IDE checks the dependencies.

`-df'

Print to stderr how the IDE searches for files.

`-ds'

Print to stderr how the IDE expands the specs.

`-da'

Turns on all of the above

You can also combine these options like `-dct', which is the same as `-dc -dt'.

To examine this debugging information, it is the best to use the redir command, to redirect the stderr to a file like

redir -e err rhide -da project

which will redirect stderr to the file `err'.

Under GNU/Linux use the following command:

rhide -da project 2>err

Each of the letters above (after `-d') can be prefixed by a `-' or a `+' to explicitely turn the flag on or off. For instance `-dc' and `-d+c' are the same and `-da-c' selects all debugging options except the `-dc' switch.

If you want to supply certain switches for RHIDE as a default, you may put them into the environment variable `$(RHIDEOPT)'. The contents of this variable is used before the the real commandline is parsed. That means you can overwrite the switches from the environment variable.

1.6 The program GPR2MAK

In RHIDE you have only the possibility to say, if in the generated makefile all dependencies should be included or not. With `gpr2mak' you can tell also to create recursively all the needed makefiles. This makes sense only if you have included other projects in your project.

Here are the possible commandline options for `gpr2mak'.

`-d'

Include all dependencies in the makefile

`-d-'

Include only the needed dependencies to create the final program or library.

`-r'

Call `gpr2mak' recursively, if there are other projects part of the project.

`-r-'

Do not call `gpr2mak' recursively.

`-o OUTFILE'

Use `OUTFILE' instead of the project name (with the suffix `.mak') as the created makefile. If you want to write the makefile to stdout, use `-' as `OUTFILE'.

And the complete syntax for calling `gpr2mak' is also:

gpr2mak [-d[-]] [-r[-]] [-o OUTFILE] project-file

If you give no options, (the project-file must be given), `gpr2mak' assumes the flags `-d- -r-' as default.

1.7 The program GPREXP

GPREXP replaces all directories, which are used also in the dialogs like the directory customizations for include file searches, by the variables if they are known there.

1.8 First steps with RHIDE

Here I will give you some instructions for the first steps to get contact with RHIDE.

1.8.1 What are these so called projects
1.8.2 Creating your first project

1.8.1 What are these so called projects

In general RHIDE creates for each project two files. One for the project itself (it has the suffix `.gpr') and one for the desktop related things (it has the suffix `.gdt').

To create a new project either run rhide with a not existing project name as argument or open within RHIDE a project by selecting a name which is not existent.

1.8.2 Creating your first project

For the next instructions I will assume, that you want to create a project for the standard "Hello world" program in the current directory. Create now the new project by running

rhide hello

and you will see an empty desktop and one window opened, the project window. This window will show you that there is no file defined for your project. If the project window is selected, (it has a double frame), then hit there Ins and you will be prompted for adding an item to your project.

Type in the input line now `hello.c' and hit ENTER. Now hit ESC to leave the dialog. You will see now, that the project window contains a line with `hello.c'.

Now hit ENTER on that filename and you will get an empty editor window named `hello.c' prepended by the current directory. In this editor window you can type now the program:

#include <stdio.h> int main() { printf("Hello world!\n"); exit(0); }

Now you can select from the Run-menu the Run entry (or use the hotkey Ctrl+F9) and RHIDE will do all the necessary steps to compile, link and execute the program.

If everything was correct (no typing errors) or some other error, you will get a message box where RHIDE tells you, that the program exited with an exit code of 0. (This is the value, which you have specified in your program above in the exit(0); statement) This box you can close with ENTER or ESC.

To see the output of the program, you can switch now to the user screen with Alt+F5 or from the menu (Windows/User screen). To return back to RHIDE hit any key.

1.9 Environment variables

RHIDE uses many environment variables for it's configuration and behavior. This includes also some standard variables, which are used by the in RHIDE linked libraries. These are:

$(LOCALEDIR)

This should point to the directory, where your locale files are stored. If it is not set, RHIDE tries to get the system default value, which is for GNU/Linux `/usr/share/locale' and for DJGPP `$(DJDIR)/share/locale'.

$(INFOPATH)

This is a pathlist of directories, where your INFO files are stored. If not set, RHIDE tries the standard directory, which should for GNU/Linux `/usr/info' and for DJGPP `$(DJDIR)/info'.

$(RHIDEOPT)

This variable can be used, to define global RHIDE commandline options. The value of this variable is used, as if the contents are given on commandline before any of the real commandline options. Which means, they can be overwritten on the commandline.

$(ESCDELAY)

This variable is used ONLY in the GNU/Linux version, where it defines the delay after pressing ESC to wait for another keypress to simulate an Alt keycode. The value is given in milliseconds and defaults to 1000.

$(LANGUAGE)

This variable is used to specify the language, in which RHIDE should communicate with you. The contents of this variable should be the ISO 2-character code of your country.

$(RHIDE_SHARE)

With this variable you can tell RHIDE where it should look at first for it's configuration files.

1.9.1 Setting environment variables for RHIDE
1.9.2 Where to store the environment file

1.9.1 Setting environment variables for RHIDE

There are some different ways for setting environment variables for RHIDE. One of them is to set them like any other environment variable on your system. But this means that these variables are visible also by all the other programs.

When using the DJGPP version, you can set them in your `djgpp.env' file either at the beginning as global variables for any DJGPP program or in a special section `[RHIDE]' only for RHIDE. Please read the doc about the format of the `djgpp.env' file for more information.

Derived from the technique used on DJGPP for setting environment variables which are visible only for DJGPP programs, I have added in RHIDE a similar thing. RHIDE can read environment variables also from a file called `rhide.env'.

The syntax of this file is very simple. Each line has one of the following syntax:

VARIABLE=CONTENTS

Which means, that the environment variable `VARIABLE' should become the contents `CONTENTS' where `CONTENTS' can be also a variable, which is expanded at runtime.

include OTHER_ENV_FILE

Such a line tells RHIDE to read in at that point the file `OTHER_ENV_FILE' as environment file. The name `OTHER_ENV_FILE' can be also an environment variable, which is expanded before reading the file.

The word `include' may optionally also start with a dash -, to be compatible with GNU make.

# comments

A line, which begins with a `#' means, that this line is ignored. It can be used for you to write there some comments about that file.

export VARIABLE=CONTENTS

This is the same syntax as without the `export' at the beginning of the line but it tells RHIDE to place the variable also in the environmen so also other programs (called by RHIDE) can see this variable.

RHIDE is very powerful in handling the environment variables. Most of it is taken from the behavior of GNU make. On this great things depend, that a variable name can consist also of other variables, which are computed when the variable should be expanded.

In general, you can use the `rhide.env' files very similar to makefiles for GNU make if you think there only about the variables and functions from GNU make.

As an example of this, you can take a look on the RHIDE sources in the `rhide.env' files. There I'm using, for instance, the RHIDE builtin variable $(RHIDE_OS) to define the libraries, which are linked in RHIDE depending on the operating system where RHIDE is built.

An other example is distributed with RHIDE in it's binary archives as `rhide_.env' which is commented and should be in a directory `.../share/rhide/' where the `...' stand for a different directory on different OS's. (on DJGPP it is %DJDIR% and on GNU/Linux it is /usr/local )

Here is a part of the environment file `rhide.var' in the main RHIDE source directory (which is included by `rhide.env' with

include $(RHIDESRC)/rhide.var

RHIDE_OS_LIBS_Linux=ncurses gpm m RHIDE_OS_LIBS_DJGPP_idegc.exe=dbg RHIDE_OS_LIBS_DJGPP=$(RHIDE_OS_LIBS_DJGPP_$(MAIN_TARGET)) RHIDE_OS_LIBS=$(RHIDE_OS_LIBS_$(RHIDE_OS))

The RHIDE builtin linker spec see section 4.5 Builtin compiler specs includes also $(RHIDE_OS_LIBS) when linking. Since RHIDE can be built on DJGPP and GNU/Linux and on these different operating systems I have to link different libraries.

Description of the above: When linking on DJGPP the file `idegc.exe' (which is RHIDE) I have to include (in addition to all the other libraries) `libdbg.a', which contains all the DJGPP specific debugging functions. This is done at runtime by expanding RHIDE_OS_LIBS. Here are the steps, how RHIDE expands the variable RHIDE_OS_LIBS:

$(RHIDE_OS_LIBS) -> $(RHIDE_OS_LIBS_$(RHIDE_OS)) $(RHIDE_OS_LIBS_$(RHIDE_OS)) -> $(RHIDE_OS_LIBS_DJGPP) $(RHIDE_OS_LIBS_DJGPP) -> $(RHIDE_OS_LIBS_DJGPP_$(MAIN_TARGET)) $(RHIDE_OS_LIBS_DJGPP_$(MAIN_TARGET)) -> $(RHIDE_OS_LIBS_DJGPP_idegc.exe) $(RHIDE_OS_LIBS_DJGPP_idegc.exe -> dbg

In a similar way it expands on GNU/Linux to

$(RHIDE_OS_LIBS) -> ncurses gpm m

1.9.2 Where to store the environment file

At first it searches for a global file in `/usr/local/share/rhide' (on GNU/Linux) or `$(DJDIR)/share/rhide'. Then it searches in `$(HOME)' and at last in the current directory.

RHIDE does not only a search, it also loads the file, if it was found in any of the above mentioned directories. That means, if in all these directories `rhide.env' exists, it is loaded. This has the effect, that you can define some global defaults which can be overwritten with a `rhide.env' in the current or your home directory.

If you need a sample usage of `rhide.env', please take a look at the RHIDE sources.