libs-base/Documentation/manual/Introduction.texi

@paragraphindent 0

@node Introduction
@chapter Introduction

The aim of this manual is to introduce you to the Objective-C language and the
GNUstep development environment, in particular the Base library. The manual is
organised to give you a tutorial introduction to the language and APIs, by
using examples whenever possible, rather than providing a lengthy abstract
description.

While Objective-C is not a difficult language to learn or use, some of the
terms may be unfamiliar, especially to those that have not programmed using an
object-oriented programming language before. Whenever possible, concepts will
be explained in simple terms rather than in more advanced programming terms,
and comparisons to other languages will be used to aid in illustration.


@section What is Object-Oriented Programming?
@cindex object-oriented programming

There are several object-oriented (OO) programming languages in common use
today and you have probably heard of some of them: C++ and Java for example,
and of course Objective-C. OO languages all have one thing in common: they
allow you to design and write programs in a different way than if you used a
traditional procedural language like C or Pascal.

Procedural languages provide the programmer with basic building blocks that
consist of data types, (integers, characters, float etc) and functions that
act on that data. This forces the program designer to design the program using
these same building blocks. Quite often this requires quite a leap in
imagination between what the program must do and how it can be implemented.

Object-oriented languages allow the program designer to think in terms of
building blocks that are closer to what the program will actually do. Rather
than think in terms of data and functions that act on that data, OO languages
provide you with objects and the ability to send messages to those
objects. Objects are, in a sense, like mini programs that can function on
their own when requested by the program or even another object.

For example, an object may exist that can draw a rectangle in a window; all
you need to do as a programmer is send the appropriate messages to that
object. The messages could tell the object the size of the rectangle and
position in the window, and of course tell the object to draw itself. Program
design and implementation is now reduced to sending messages to the
appropriate objects rather than calling functions to manipulate data.

@subsection Some Basic OO Terminology
@cindex basic OO terminology

OO languages add to the vocabulary of more traditional programming languages,
and it may help if you become familiar with some of the basic terms before
jumping in to the language itself.

@b{Objects}

As stated previously, an object is one of the basic building blocks in OO
programming. An object can receive messages and then act on these messages to
alter the state of itself (the size and position of a rectangle object for
example). In software an object consists of instance variables (data) that
represent the state of the object, and methods (like C functions) that act on
these variables in response to messages.

Rather than 'calling' one of its methods, an object is said to 'perform' one
of its methods in response to a message. (A method is known as a 'member
function' in C++.)

@b{Classes}

All objects of the same type are said to be members of the same class. To
continue with the rectangle example, every rectangle could belong to a
rectangle class, where the class defines the instance variables and the
methods of all rectangles.

A class definition by itself does not create an object but instead acts like a
template for each object in that class. When an object is created an
'instance' of that class is said to exist. An instance of a class (an object)
has the same data structure (instance variables) and methods as every other
object in that class.

@b{Inheritance}

When you define a new class you can base it on an existing class. The new
class would then 'inherit' the data structure and methods of the class that
you based it on. You are then free to add instance variables and methods, or
even modify inherited methods, to change the behavior of the new class (how it
reacts to messages).

The base class is known as the 'superclass' and the new class as the
'subclass' of this superclass. As an example, there could be a superclass
called 'shapes' with a data structure and methods to size, position and draw
itself, on which you could base the rectangle class.

@b{Polymorphism}

Unlike functions in a procedural program such as C, where every function must
have a unique name, a method (or instance variable) in one class can have the
same name as that in another class.

This means that two objects could respond to the same message in completely
different ways, since identically named methods may do completely different
things. A draw message sent to a rectangle object would not produce the same
shape as a draw message sent to a circle object.

@b{Encapsulation}

An object hides its instance variables and method implementations from other
parts of the program. This encapsulation allows the programmer that uses an
object to concentrate on what the object does rather than how it is
implemented.

Also, providing the interface to an object does not change (the methods of an
object and how they respond to received messages) then the implementation of
an object can be improved without affecting any programs that use it.

@b{Dynamic Typing and Binding}

Due to polymorhism, the method performed in response to a message depends on
the class (type) of the receiving object. In an OO program the type, or class,
of an object can be determined at run time (dynamic typing) rather than at
compile time (static typing).

The method performed (what happens as a result of this message) can then be
determined during program execution and could, for example, be determined by
user action or some other external event. Binding a message to a particular
method at run time is known as dynamic binding.

@section What is Objective-C?
@cindex what is Objective-C?
@cindex Objective-C, what is?

Objective-C is a powerful object-oriented (OO) language that extends the
procedural language ANSI C with the addition of a few keywords and compiler
directives, plus one syntactical addition (for sending messages to
objects). This simple extension of ANSI C is made possible by an Objective-C
runtime library (libobjc) that is generally transparent to the Objective-C
programmer.

During compilation of Objective-C source code, OO extensions in the language
compile to C function calls to the runtime library. It is the runtime library
that makes dynamic typing and binding possible, and that makes Objective-C a
true object-oriented language.

Since Objective-C extends ANSI C with a few additional language constructs
(the compiler directives and syntactical addition), you may freely include C
code in your Objective-C programs. In fact an Objective-C program may look
familiar to the C programmer since it is constructed using the traditional
@code{main} function.

@example
#include <stdio.h>
#include <objc/objc.h>

int main (void)
@{

  /* Objective C and C code */
  
  return(0);
@}
@end example

Objective-C source files are compiled using the standard GNU @b{gcc}
compiler. The compiler recognises Objective-C source files by the @code{.m}
file extension, C files by the @code{.c} extension and header files by the
@code{.h} extension.

As an example, the command @b{$gcc -o testfile testfile.m -lobjc} would
compile the Objective-C source file @code{testfile.m} to an executable named
@code{testfile}. The @code{-lobjc} compiler option is required for linking an
Objective-C program to the runtime library.  (On GNU/Linux systems you may
also need the @code{-lpthreads} option.)

The GNUstep @b{make} utility provides an alternative (and simple) way to
compile large projects, and this useful utility is discussed in the next
section.

Relative to other languages, Objective-C is more dynamic than C++ or Java in
that it binds all method calls at runtime.  Java gets around some of the
limitations of static binding with explicit runtime ``reflection'' mechanisms.
Objective-C has these too, but you do not need them as often as in Java, even
though Objective-C is compiled while Java is interpreted.  More information
can be found in Appendix @ref{Objective-C Java and C++}.

@section History
@cindex history of Objective-C
@cindex Objective-C, history
@cindex history of NeXTstep
@cindex NeXTstep, history
@cindex history of OpenStep
@cindex OpenStep, history

Objective-C was specified and first implemented by Brad Cox and his company
Stepstone Corporation during the early 1980's.  They aimed to minimally
incorporate the object-oriented features of Smalltalk-80 into C.  Steve Jobs's
NeXT licensed Objective-C from StepStone in 1988 to serve as the foundation of
the new NeXTstep development and operating environment.  NeXT implemented its
own compiler by building on the @i{gcc} compiler, modifications that were
later contributed back to gcc in 1991.  No less than three runtime libraries
were subsequently written to serve as the GNU runtime; the one currently in
use was developed by Danish university student Kresten Krab Thorup.

Smalltalk-80 also included a class library, and Stepstone's Objective-C
implementation contained its own library based loosely on it.  This in turn
influenced the design of the NeXTstep class libraries, which are what GNUstep
itself is ultimately based on.

After NeXT exited the hardware business in the early 1990s, its Objective-C
class library and development environment, @i{NeXTstep}, was renamed
@i{OpenStep} and ported to run on several different platforms.  Apple acquired
NeXT in 1996, and after several years figuring out how to smooth the
transition from their current OS, they released a modified, enhanced version
of the NeXTstep operating system as Mac OS X, or ``10'' in 1999.  The class
libraries in OS X contain additions related to new multimedia capabilities and
integration with Java, but their core is still essentially the OpenStep API.

This API consists of two parts: the @i{Foundation}, a collection of
non-graphical classes for data management, network and file interaction, date
and time handling, and more, and the @i{AppKit}, a collection of user
interface widgets and windowing machinery for developing full-fledged
graphical applications.  GNUstep provides implementations of both parts of
this API, together with a graphical engine for rendering AppKit components on
various platforms.


@section What is GNUstep?
@cindex what is GNUstep?
@cindex GNUstep, what is?

GNUstep is an object-oriented development environment that provides the
Objective-C programmer with a range of utilities and libraries for building
large, cross-platform, applications and tools.  It is split into three
components: @b{Base}, non-graphical classes corresponding to the NeXTstep
@i{Foundation} API, @b{GUI}, consisting of graphical classes corresponding to
the NeXTstep @i{AppKit} API, and @b{Back}, a modular framework for rendering
instance of the GUI classes on multiple platforms.

GNUstep is generally compatible with the OpenStep specification and with
recent developments of the MacOS (Cocoa) API. Where MacOS deviates from the
OpenStep API, GNUstep generally attempts to support both versions.  See
Appendix @ref{Compliance to Standards} for more detailed information.

This manual does not discuss the full functionality of GNUstep but
concentrates on using the GNUstep Base library to create non-graphical
programs, and the GNUstep @b{make} utility to compile these programs. Further
information about GNUstep can be found at @url{http://gnustep.org}.


@subsection GNUstep Base Library
@cindex GNUstep base library

The GNUstep base library contains a powerful set of non-graphical Objective-C
classes that can readily be used in your programs. At present there are
approximately 70 different classes available, including classes to handle
strings and arrays, dates and times, distributed objects, URLs and file
systems (to name but a few).  It is similar to but more stable than the
non-graphical portion of the Java Development Kit (JDK) API (see Appendix
@ref{Objective-C Java and C++} for more information).

Classes in the base library are easily identified since they begin with the
upper case characters 'NS', as in @code{NSString}. Some examples in this
manual use classes from the base library, but for complete documentation on
the base library see the @uref{../Reference/index.html, API documentation}.


@subsection GNUstep Make Utility
@cindex GNUstep make utility
@cindex make utility, GNUstep

The GNUstep @b{make} utility is the GNU version of the UNIX make utility, plus
a number of predefined rules specialized for building GNUstep projects. So
what does it do? It simplifies the process of building (compiling and linking)
a large project. You simply type @b{make} at the command prompt and the make
utility takes care of file dependencies, only re-compiling source files that
have changed, or that depend on files that have changed, since the last 'make'
(a header file for example).  It also takes care of including the proper
GNUstep header and library references automatically.

Before using @b{make} you must first create a 'makefile' that lists all the
files and file dependencies in your project. The easiest way to do this is to
copy an existing makefile and change it to suit your own project.

The make utility will be used to build the Objective-C examples shown in this
manual, and when an example can be compiled then the makefile will also be
shown.  For a full description of the make utility see its
@uref{../../Make/Manual/make_toc.html, documentation}.

@subsection A Word on the Graphical Environment
@cindex graphical programming
@cindex AppKit
@cindex GUI

The GNUstep @b{GUI} component is discussed
@uref{../../Gui/ProgrammingManual/manual_toc.html, elsewhere}, but a brief
overview is useful here.  GNUstep GUI provides a collection of classes for
developing graphical applications, including windows, controls (also known as
widgets, and back-end components for event handling and other functions. 
Internally, the implementation is divided into two components, the @i{back end} 
and the @i{front end}.  The front end provides the API to the developer, and 
makes display postscript (DPS) calls to the back end to implement it.  The 
back-end converts the DPS calls into calls to the underlying window system.  If 
you install GNUstep from source, you must first compile and install the front end,
then compile and install the back end.

Implementations of the back-end have been produced for both X11 (Linux/UNIX
systems), and Windows.  There is also a quasi-native display postscript system
similar to what was available on the NeXT but using Ghostscript to render to
X11.  This implementation is largely complete, but proved to be inefficient
and difficult to optimize relative to the current back-end framework (which
converts the DPS from the front end to window drawing commands immediately
rather than relying on a postscript stack).

@comment{Add brief blurbs on Gorm and Renaissance.}


@subsection The GNUstep Directory Layout
@cindex directory layout
@cindex filesystem layout
@cindex layout, filesystem

The directories of a GNUstep installation are organized in a fashion that
balances compatibility with NeXTstep/OpenStep/OS X with traditional Unix
filesystem conventions.  The highest level of organization consists of four
@i{domains} - the System, Local, Network, and Users.  @i{System} holds the
main GNUstep installation, including the Base and GUI libraries and
documentation.  @i{Local} holds third party applications, custom extension
libraries, etc., analogously to @code{/usr/local} on a Unix system.
@i{Network} mounts shared files in a networked environment.  @i{Users} usually
exists as @code{$HOME/GNUstep} and holds preferences files and personal
application data.  There is further
@uref{../../../User/GNUstep/filesystem_toc.html, documentation} available on
the complete directory layout.

Usually, on a Unix-type system, the GNUstep installation will be found under
@code{/usr/lib/GNUstep}.


@section Building Your First Objective-C Program
@cindex your first Objective-C program

The following example will show you how to create and compile an Objective-C
program. The example simply displays a text message on the screen, and there
are easier ways to to do this, but the example does demonstrate a number of
object-oriented features of Objective-C, and also demonstrates the use of
@b{make} to compile an Objective-C program.

@enumerate

@item
Create a new project directory to hold your project.@*@*

@item
Create the following Objective-C source code using your favourite text
editor and save it in the project directory with the filename @code{source.m}.

@example
#include <stdio.h>

/* 
 * The next #include line is generally present in all Objective-C
 * source files that use GNUstep.  The Foundation.h header file
 * includes all the other standard header files you need.
 */
#include <Foundation/Foundation.h>  

/*
 * Declare the Test class that implements the class method (classStringValue).
 */
@@interface Test
+ (const char *) classStringValue;
@@end

/*
 * Define the Test class and the class method (classStringValue).
 */
@@implementation Test
+ (const char *) classStringValue;
@{
  return "This is the string value of the Test class";
@}
@@end

/*
 * The main() function: pass a message to the Test class
 * and print the returned string.
 */
int main(void)
@{
  printf("%s\n", [Test classStringValue]);
  return 0;
@}
@end example

The text between comment markers (/* */) is ignored by the compiler but
indicates to someone reading the source file what each part of the program
does. The program is an example of a (class) method responding to a
message. Can you see how it works?@*@*

A message is sent to the @code{Test} class as an argument to @code{printf()},
requesting the string value of that class. The @code{Test} class performs its
@code{classStringValue} method in response to this message and returns a
string that is finally printed. No object is created in this program since a
class method does not require an instance of a class in order to respond to a
message.@*@*

You will learn more about class methods in the next chapter.@*@*

@item
Now create the makefile, again using your favourite text editor, and save it
in the same project directory with the filename @code{GNUmakefile}.

@example
include $(GNUSTEP_MAKEFILES)/common.make

TOOL_NAME = LogTest
LogTest_OBJC_FILES = source.m

include $(GNUSTEP_MAKEFILES)/tool.make
@end example

If you look at the makefile above you will notice the two lines that tell the
make utility to build a tool with the filename @code{LogTest} from the
Objective-C source file @code{source.m}. You could copy and modify this
makefile for later projects you may have: just change the tool name and list
the new source files.@*@*

The two 'include' lines are just a way of keeping your makefile simple, by
including two 'ready-made' makefiles that someone else created.@*@*

@item
Before you can execute this makefile you must first set your GNUstep
environment variables.  Among other things this defines the
@code{GNUSTEP_MAKEFILES} variable referenced above.  The simplest way to do
this is to execute one of the following commands (you must first locate your
GNUstep installation manually):

C shell:@*
@code{source <GNUstep root>/System/Library/Makefiles/GNUstep.csh}

Bourne shell:@*
@code{. <GNUstep root>/System/Library/Makefiles/GNUstep.sh}

On most Unix systems, GNUstep is installed in @code{/usr/lib/GNUstep}.
(@uref{../../../User/GNUstep/filesystem_toc.html, Directory layout
documentation}.)

@item
You can now compile the project using make. At the system command prompt,
change to the project directory and enter the @b{make} command.@*@*

@item
Run the program (on Unix enter @b{./obj/LogTest}
at the command prompt). The message "This is the string value of the Test class" 
will be displayed (assuming there were no errors).

@end enumerate

You have now compiled and run your first Objective-C program. Hungry for more?
Then read on.