Welcome to GEOS development. This document guides you through the CD-ROM installation procedure; it also describes your environment configuration, shows how to set up multiple NT machines, and lists the most common setup difficulties in a short troubleshooting guide.
If you are familiar with GEOS development, please review the SDK changes described in Compiling GEOS Applications , and Directory Structure , before you begin compiling and debugging geodes.
You can find complete information on the tools mentioned here (Swat, pmake, etc.) in the Tools book.
1 System Requirements
2 Installation and Setup
2.1 Installation Details
2.2 NT Configuration
2.3 Environment Configuration
2.4 Registry Configuration
3 Launching NT GEOS and Swat
4 Compiling GEOS Applications
5 Directory Structure
5.1 Branches
5.2 Main Directories
5.3 Target Directories
5.4 Developing In Your Working Branch
5.5 Multi-Developer Projects
6 Troubleshooting
The GEOS SDK runs on a Windows NT workstation (version 3.51 or later). The SDK also requires a perl interpreter (a shareware copy is provided on the CD-ROM) and the Borland C/C++ compiler, version 4.0 or later. (We recommend versions 4.X over 5.0; see Compiling GEOS Applications .)
You can install the GEOS NT SDK as either a standalone SDK for just one computer or as a server/client SDK on a network drive. The former is suited for single developers while the latter allows multiple developers to work on different aspects of the same project simultaneously. In either case, the steps for installation are similar. In summary,
setup
from the GEOS NT SDK CD-ROM.Some additional steps are required for server-client installations.
Steps for installing the GEOS NT SDK:
setup
from the GEOS NT SDK CD-ROM.
setup.exe, found in the CD-ROM's topmost directory. The installer will prompt you to choose from one of three installation options: Server,
Client, or
Standalone.
A server installation installs the shared components of the SDK on a network server so that it accessed from multiple client workstations.
A client installation:
A standalone installation:
Note that the root for the client and server portions must be the same. For example, if the server SDK is in f:/prog/sdks/pcgeos, then the local working directory must look like c:/pcgeos/jdoe, where the two italicized components match. This applies to both standalone and client/server development. Typically, this root directory is "pcgeos", e.g. S:\PCGEOS. (For more information, see Directory Structure.)
install.bat
after unzipping; reply "y" (the default) to the install options.GeosSetup.exe, as described in Registry Configuration.The installer completes the following for you automatically; they are included here for reference only.
System module of the NT Control Panel.
The compiling and linking tools use the following environment variables to find executables and include files. These variables are set from the
system
module of the control panel, not an autoexec file.
setup
sets these environment variables for you; they are included here for reference only.
pmake
. This must be set to
@dosfront bcc
for versions of the Borland compiler prior to 5.0.
To check your registry settings, run GeosSetup.exe from the GEOS SDK Program Group. (Note: do not confuse GeosSetup.exe for setup.exe, which is the installer program.)
Swat (here and on its command line) prefers forward slashes in directory paths; backslashes are sometimes inadvertently interpreted as special characters (\tools as <TAB> ools, for instance).
pmake
to run properly the penultimate element of
Local Root
must have the same name as the last element of
SDK Root
. (It need not be the actual
SDK Root
directory, however.) The last element may be named anything, but user names are typically used.
The GEOS
Setup
window also includes a selector for the communication mode. Choose
Local (NT native)
to instruct Swat to attach to your NT GEOS window, or choose
Remote (Serial)
to instruct Swat to attach to an external device, with appropriate
Speed
and
Port
settings.
You may store and recall a number of different setups by using the Current Setup selector. The Setup names have no intrinsic meaning.
You will find example shortcuts for launching the NT GEOS demo in the GEOS SDK Program Group. You can define additional shortcuts to launch NT GEOS by right-clicking on the root window (NT 4.0) or selecting the menu item File -> New on the Program Manager (NT 3.51). Specify a command such as
c:\pcgeos\target\n9000.nc\swat.exe /s loader.exe
(modified as desired); you must also specify a working directory (under
target\
) corresponding to the simulation you wish this icon to run. For command examples, refer to the batch files described below.
To launch a target device window from the command line, change-directory to your target area (for example,
\pcgeos\target\n9000.ec\
) and type
start s
at the prompt. (
s.bat
is supplied in the target directory templates, and
start
tells NT to run the command in a new window.)
s.bat
is a batch file which executes the Swat stub;
ss.bat
forces the demo to wait for a host Swat debugger to attach. Execute
start s
(or
ss
) in your non-EC directory to run the non-EC version of the Swat stub. To run the non-Swat demo, use
start geos
, which executes
loader{ec}.exe
without the Swat stub.
In summary, each of these demos is available in both the EC and non-EC target directories:
ss.bat Demo with Swat stub, wait for host Swat s.bat Demo with Swat stub, do not wait geos.bat Demo without Swat
Launch the host Swat debugger from an icon in the GEOS SDK Program Group or from the command line with
swat
(or
start swat
). (Be careful not to run a Swat stub if your current directory is a target directory; you want to run
swat.exe
from
pcgeos\bin\
.) Debugging with Swat in the NT environment is the same as that in the old DOS one; use
^
C and
c
to interrupt and continue execution,
att
and
det
to attach and detach, and so forth.
The Swat window size may be increased by modifying the window-size property of your command windows in general or your Swat shortcut in particular. Any change made to a window after Swat is launched will not be recognized.
You can instruct Swat to attach to an external Communicator device or PC emulator by running GEOS
Setup
prior to launching Swat and selecting the serial
Communication Mode
and an appropriate
Comm port
.
You can stop NT GEOS by entering
detach
or
quit
when Swat is attached. Otherwise, you can stop the demo by clicking the kill (X) button on the right of the titlebar, double-clicking the top-left titlebar menu, or using NT's task manager.
If you have a file called . swat in the root of your private directory and run the GEOS Setup program to change the "Swat Init File" field to point to that file, Swat will execute Swat commands in that directory when it starts up. Below is a short example of a .swat file:
srcwin 15 sd hello
The
srcwin
command sets up a source-code window at the bottom of the screen. The
sd
command changes the symbolic default to be the "hello" thread. Any time Swat does not recognize a name in the current thread, it will see if the name has meaning in the hello thread.
To compile GEOS C code, you need the following third-party software installed on your system:
Your PATH variable must include the Borland compiler's bin directory and the directory containing the perl interpreter. If you installed Borland C++ after the NT SDK or if you set up a network environment, you may need to set the environment variable GOC_COMPILER_DIR to reflect the compiler's location. Refer to Environment Configuration .
Borland C++ is a separate product on its own CD-ROM. We strongly recommend that you install version 4.5 of the compiler, included with most distributions of version 5.0. A change in the compiler's handling of #pragma options creates errors (not reported at compile time) in geodes compiled with version 5.0. You must install the 32-bit Windows compiler, a part of the "typical" installation.
A shareware version of the perl installer has been included with the SDK; refer to Installation and Setup for installation instructions.
All of the tools needed to compile geodes (goc, glue, etc.) have been included in the
\pcgeos\bin
directory. Use
mkmf
and
pmake
to compile, as described in the chapter "Using Tools" of the Tools book. (
pmake depend
is not needed in the NT environment.)
After compiling, copy resulting geodes directly to your target tree from the command line or use Swat's
send
command after attaching.
world\extrapps
is the appropriate demo directory for extras on the Nokia 9000i Communicator.
If you are familiar with GEOS development in the DOS environment, note the following changes:
pmake depend
after
mkmf
; use it only to re-make dependencies when you change your include-file statements.
copy
to put compiled geodes in your target tree, although Swat's
send
command works as before.
detach
or
quit
command.The directory structure in the NT SDK differs significantly from that of the DOS SDK. The change reflects standardization across platforms and facilitates multi-engineer development in a network environment.
Developing In Your Working Branch
Every device that runs GEOS contains a specific version of the kernel, applications, and various ancillary libraries and drivers. The directory path that contains the specific version of the device software is called a Branch. (The "Trunk" is a collection of all the files from all the different branches. As a developer, you will never need to utilize any files on the Trunk.)
Branch directories are located directly under the PCGEOS directory ( i.e. , the main SDK directory) and were developed as a way to "lock in" a device-specific image of the development system. For example, the N9000V20 branch contains all the header and symbol files for Version 2.0 of the Nokia 9000 SDK. When you install an SDK for another GEOS device, you will find a new branch directory specific to that device under the PCGEOS directory.
The figure below shows the directory layout of the Nokia 9000i SDK (Version 1.1). This may appear slightly different on newer SDKs. This directory tree contains two Branch directories: N9000V11 and {Working_Branch} . ({ Working_Branch } is your personal development area; see Developing In Your Working Branch for a complete explanation of Working Branches)
If multiple developers are working on a project, then the branches should be separated into the local branches which reside on each engineer's machine and the shared network branch which all the project developers will access each time they compile. When performing a server install, the above directories marked "shared/network" are installed onto the network machine, and the client install places the directories marked "local" on each developer's machine. (See 5.5 Multi-Developer Projects.)
Each Branch contains the following directories:
Also contains the following subdirectories:
In addition to those directories listed above, your Working Branch contains a Target directory. This directory contains the executable and data files comprising an emulation (or "demo") of the actual GEOS device. The Target subtree mirrors the file system layout of the actual device.
Be sure to update the working directories of your GEOS SDK demo shortcuts so that they point to the Target directory in your Working Branch; for example, the shortcut to the error-checking demo for the Nokia 9000i Communicator should be \pcgeos\username\target\n9000.ec .
Network installations can make use of shared geode libraries if desired. When geodes are invoked during emulation, the current working (target) directory tree will be searched first, followed by trees specified by the top keyword under [paths] in your .ini file. For example, all of the geodes under the system subdirectory could be stored in a central, shared location in order to save disk space or allow easy updates. You can supersede shared geodes in your demo by putting custom versions (of the same name) in your private system subdirectory.
Each target directory has a
geos{ec}.ini
file. It can refer to files of standard
.ini
settings under its
[paths]
category; it also contains superseding information necessary for running NT GEOS. When editing
.ini
files, take care to end each line with a
CR-LF
pair or use an editor (such as DOS
edit
) that does so transparently. More information on
.ini
files in general is found in the Tools book.
The Working Branch is your private development area. By doing all your work in your Working Branch (also called your Local Root ), the Branch files can remain untouched.
You specify the directory for your Working Branch during the Local SDK Install program. The default is your login name. For example, if your login is jdoe, then your Working Branch directory is c:\pcgeos\jdoe\ . (You should also make sure that the demo shortcuts point to the Target directory in your Working Branch.)
Within your Working directory is a file called BRANCH. This file specifies which Branch directory the tools will use when compiling and linking your source code. The tools will first look for files in your Working Branch. Whatever files it does not find in your Working Branch, it will look for in the Branch specified by the BRANCH file. You need only keep the file or files that you are working on in your Working Branch and system files (such as header files) can remain on the device Branch. So, for example, a typical development sequence might look like this:
To specify which Branch the compiler and linker should use, place the name of the Branch directory in the BRANCH file. (Currently, setting the Branch field in GEOS Setup only affects which branch Swat uses; you must edit the actual BRANCH file yourself.) Initially, your BRANCH file contains N9000V20.
The system of Branch files is most helpful when there are multiple developers working on the same project. Each developer would maintain her personal working files in her own Working Branch while shared files would remain on the device Branch. As development progresses, each developer can "install" files to the Branch directory as she reaches stable milestones thereby allowing her co-workers to use the "installed" versions of her files. (Note: "installing" can be as simple as copying the files by hand or can be handled by a version control system.)
If you are having trouble starting the simulation or attaching Swat, consult the table below. The most common known difficulties are listed.
Does Swat report FSHOF_SET_FILE_NAME_PASSED_TO_SKELETON_DRIVER, ATTEMPTED_TO_PERFORM_UNSUPPORTED_FUNCTION_
BEFORE_APPROPRIATE_IFS_DRIVER_WAS_LOADED, or TOO_MANY_PRIMARY_FSDs?
There is a problem with the file system driver. Check
.ini
file settings and
setver
listing, referring to NT Configuration
.
gdikbd
keyboard driver.
srcwin
command fails, reporting:
Window too small
System
module of the Control Panel.
edit
to restore
CR-LF
's.
pmake
fails, reporting:
Couldn't find geos.mk.
pmake
fails, reporting:
Couldn't find stddef.h