diff --git a/ChangeLog b/ChangeLog index 802b05ed..ae4f7515 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,17 @@ +2001-02-26 Adam Fedor + + * Documenation/makedoc.make: New file mostly copied from + documenation.make. + * Documenation/makerules.make: New mostly copied from rules.make + * Documenation/gnustep-howto.texi: Moved from core/Documenation + * Documenation/faq.texi: Likewise. + * Documenation/machines.texi: Likewise. + * GNUstep-HOWTO, FAQ: Regenerated. + * README.MinGW: Moved from core + 2001-02-25 Adam Fedor - * configure.in: Separate def of LD_LIBRARY_PATH freom export. + * configure.in: Separate def of LD_LIBRARY_PATH from export. 2001-02-24 Nicola Pero diff --git a/Documentation/faq.texi b/Documentation/faq.texi new file mode 100644 index 00000000..7be88557 --- /dev/null +++ b/Documentation/faq.texi @@ -0,0 +1,876 @@ +\input texinfo @c -*-texinfo-*- +@c A FAQ for GNUstep +@c +@c This file uses the special commands @url{} and @email{}. They are +@c handled by the doc/Makefile. + +@iftex +@global@let@email=@i +@global@let@url=@samp +@end iftex + +@c @ifinfo +@c @definfoenclose email, <, > +@c @definfoenclose url `, ' +@c @end ifinfo + +@node Top, GNUstep General Information, (dir), (dir) +@chapter GNUstep Frequently Asked Questions with Answers + +Last updated @today{} +Please send corrections to @email{gnustep-maintainer@@gnu.org}. + +@menu +* GNUstep General Information:: +* Compiling and Developing:: +* GNU Objective C Compiler and Objective C Runtime Library:: +* GNUstep Base Library:: +* GNUstep GUI Library:: +* GNUstep DisplayGhostScript Server:: +@end menu + +@node GNUstep General Information, Compiling and Developing, Top, Top +@section GNUstep General Information + +@menu +* What is GNUstep?:: +* What is the OpenStep standard?:: +* What platforms does GNUstep run on?:: +* Does GNUstep run on Windows?:: +* What is GNUstep's position towards KDE and the GNOME project?:: +* Is the Objective C API for GTK related?:: +* How about implementing parts of the Application Kit with GTK?:: +* Which compiler can I use? Where can I get it?:: +* Which Foundation Library can I use?:: +* How do you use the gnustep-make package?:: +* How can I get GNUstep?:: +* How do you run GNUstep?:: +* Is there a web site?:: +* When is GNUstep intended to be available?:: +* What is usable?:: +@end menu + +@node What is GNUstep?, What is the OpenStep standard?, GNUstep General Information, GNUstep General Information +@subsection What is GNUstep? + +GNUstep is the Free Software Foundation's effort to implement NeXT +Software Inc.'s (now Apple Inc.) OpenStep Standard. The project is not +finished, however some components are useable now. + +The GNUstep project consists of the following sub-projects: + +@itemize @bullet + +@item GNU Objective C Compiler and Objective C Runtime Library - +Although not actually a component of GNUstep, GCC and the GNU +Objective C Runtime Library are integral to GNUstep, since they are used +to make every GNU Objective C program. + +@item GNUstep Base Library - Code for non-graphical objects, such as +strings, collections, archiving support and distributed objects +messaging. (Including functionality similar to OpenStep's +@samp{FoundationKit}.) + +@item GNUstep GUI Library - Code for graphical objects used in making a +Graphical User Interface (GUI). This includes buttons, sliders, text +fields, windows, menus, etc. (Including functionality similar to +OpenStep's @samp{AppKit}.) + +@item GNUstep DisplayGhostscript Server - A server that draws PostScript +graphics to the screen, and receives events from the keyboard and +mouse. It is based on GhostScript. There is also an DPS extension to +Xfree*6 that is usable. + +@item Various Tools and applications, including GORM, The GNUstep +interface builder for graphically assembling application interfaces, and +ProjectCenter, a project manager. + +@end itemize + +@node What is the OpenStep standard?, What platforms does GNUstep run on?, What is GNUstep?, GNUstep General Information +@subsection What is the OpenStep standard? + +OpenStep is an Application Programming Interface (API) for creating +applications using the Objective C language. It was published by NeXT +Computer Inc. in 1994. + +OpenStep consists of three parts: the @samp{FoundationKit}, a library of +non-graphical objects; the @samp{AppKit}, a library of objects usful in +creating graphical applications; and @samp{Display Postscript}, an +interface for drawing to the screen using the PostScript graphics +language. + +You can obtain a copy of the OpenStep standard from the GNUstep web site +@url{http://www.gnustep.org} or it's mirror sites. + +@node What platforms does GNUstep run on?, Does GNUstep run on Windows?, What is the OpenStep standard?, GNUstep General Information +@subsection What platforms does GNUstep run on? + +Well tested current builds: +@example + Ix86/GNU-Linux + PPC/GNU-Linux +@end example +Recent builds - +@example + Ix86 Unixware-2.? Ix86 FreeBSD-3.0 (ELF) Ix86 OpenBSD-2.4 (static + libraries) Sparc SUNOS-4.1.3 PowerPC GNU/Linux +@end example + +Probably a few days porting to any other Unix system where current +gcc/egcs compilers and gdb debugger work. See the +GNUstep-HOWTO file or @url{http://www.gnustep.org/information/machines_toc.html} for more machines. + +@node Does GNUstep run on Windows?, What is GNUstep's position towards KDE and the GNOME project?, What platforms does GNUstep run on?, GNUstep General Information +@subsection Does GNUstep run on Windows? + + The primary targets for GNUstep are free 'Unix' platforms such +as GNU/Linux. + +That being said, the base library should run on Windows-NT,98 with +the Cygwin unix emulation library from Cygnus +(http://sourceware.cygnus.com/cygwin/) or the MinGW libraries. +At present there are a +few problems with networking (Distributed Objects) support, but +the library is believed to work. + +The gui library needs a win32 backend library to work under +Windows-NT. The backend library is a thin layer that converts the +GNUstep methods to handle drawing of GUI elements to calls to the +win32 api. This is a project looking for a volunteer. + +The application-wrapper used for GNUstep already allows for multiple +binaries to be stored for different systems, so you should be able +to write once, deploy anywhere. + + +@node What is GNUstep's position towards KDE and the GNOME project?, Is the Objective C API for GTK related?, Does GNUstep run on Windows?, GNUstep General Information +@subsection What is GNUstep's position towards KDE and the GNOME project? + + You can use GNUstep with GNOME and/or KDE. GNUstep displays +on top of X11. You can still do programming in C (since Objective-C +is just a superset of C), and when (if?) GCC gets around to it, +you'll be able to mix C++ and Objective-C code in the SAME file. + +GNUstep, is much more than a window manager or desktop environment. +It frees you to develop cross-platform applications without the +work of developing an OS independent framework from scratch. It +gives you lots of basic functionality, from Font Panels to Unicode +strings to Distributed Objects. + + +@node Is the Objective C API for GTK related?, How about implementing parts of the Application Kit with GTK?, What is GNUstep's position towards KDE and the GNOME project?, GNUstep General Information +@subsection Is the Objective C API for GTK related? + + No. GNUstep applications provide their GUI via the OpenStep +API, which provides fully object-oriented access to GUI manipulation. + + The object-oriented nature of the libraries and language make it much easier +for new users to create their own subclasses rather than simply using the +supplied widgets as in other frameworks. + +@node How about implementing parts of the Application Kit with GTK?, Which compiler can I use? Where can I get it?, Is the Objective C API for GTK related?, GNUstep General Information +@subsection How about implementing parts of the Application Kit with GTK? + + Yes and No - The GNUstep architecture provides a single, +platform-independent, API for handling all aspects of GUI interaction +(implemented in the gstep-gui library), with a backend architecture +that permits you to have different display models (display postscript, +X-windows, win32, berlin ...) while letting you use the same code +for printing as for displaying. Use of GTK in the frontend gui +library would remove some of those advantages without adding any. + +That being said, a backend library could be implemented using gtk +if anyone wanted to do so. Since the frontend library handles most +of the work involved in implementing the OpenStep API, the backend +is a relatively thin layer and the advantages of GTK over direct +xlib or win32 calls is likely to be minimal. If/when GTK is ported +to more systems, a backend written using it could be a valuable +asset - volunteers are, as always, wecome. + +@node Which compiler can I use? Where can I get it?, Which Foundation Library can I use?, How about implementing parts of the Application Kit with GTK?, GNUstep General Information +@subsection Which compiler can I use? Where can I get it? + + Use gcc-2.8.1 or later, from any GNU ftp site or, on some +platforms you must use egcs-1.1.1 or later, from http://egcs.cygnus.com/ + +@node Which Foundation Library can I use?, How do you use the gnustep-make package?, Which compiler can I use? Where can I get it?, GNUstep General Information +@subsection Which Foundation Library can I use? + + That depends ... + +If you only want to use the database package - gnustep-db, you can +use either the gnustep base library or libFoundation. + +If you want to develop/use GNUstep gui applications, you must use +the gnustep-base library since libFoundation is (13-Feb-2000) +missing much essential functionality. + + +@node How do you use the gnustep-make package?, How can I get GNUstep?, Which Foundation Library can I use?, GNUstep General Information +@subsection How do you use the gnustep-make package? + + Good question. Read the tutorials at the GNUstep web site. Also, use the +makefiles in the libraries, tool directories, and test applications as +examples. + +@node How can I get GNUstep?, How do you run GNUstep?, How do you use the gnustep-make package?, GNUstep General Information +@subsection How can I get GNUstep? + + Get the HOWTO from +@url{http://www.gnustep.org/resources/documentation/GNUstep-HOWTO} +Get the latest release from @url{ftp://ftp.gnustep.org}. If you're +really adventurous, get the latest snapshot by anonymous ftp from +@url{ftp://ftp.gnustep.org:/pub/daily-snapshots} + +Use anonymous CVS to keep up to date - instructions are in the +HOWTO. + +@node How do you run GNUstep?, Is there a web site?, How can I get GNUstep?, GNUstep General Information +@subsection How do you run GNUstep? + + You are presumably under the misapprehension that GNUstep is +some sort of window manager. + +It isn't. + +GNUstep is a whole load of things - primarily a set of libraries +for developing software. + +At present, it's those libraries, plus various command-line based +support tools and service providing daemons. In the future, it +will be the libraries, plus the support tools, plus various GUI +development tools, a GUI desktop/workspace application etc. + +At no stage will you ever 'run' GNUstep - you will run applications +and tools and will make use of it's services (though at some point +you may well find packages distributed as 'GNUstep' systems in the +way that you get 'Linux' systems packaged today). + +Current tools are - + +@example +The makefiles package + To make building GNUstep tools and apps simple. +The 'openapp' script + To start up a GUI application from the command line. +The defaults tools + To read, create, delete, and modify user defaults from the command + line. +The name server + To permit applications and tools to locate each other and + communicate. +The pasteboard server + To permit cut-and-paste, drag-and-drop, and to let applicationsm + and tools transparently provide services to each other. +The distributed notification center + To permit applications and tools to be notified of arbitrary + external events. +The 'make_services' program + To locate (and cache information about) applications that are + willing to provide services to other applications. +The 'set_show_service' program + A command-line utility to determine what services an application + should be permitted to offer on it's 'services' menu. +@end example + +If you want to see a sample GUI application running - you need to +build GNUstep for use with the 'xgps' library (configuring it with +with the option --with-library-combo=gnu-gnu-gnu-xgps) and look at the +example applications in the gstep-examples package. +Build 'Finger' or 'Ink' and start it with 'openapp +Finger.app' or 'openapp Ink.app' + +To look best - use WindowMaker (the currently preferred GNUstep +window manager) as your window manager. + +@node Is there a web site?, When is GNUstep intended to be available?, How do you run GNUstep?, GNUstep General Information +@subsection Is there a web site? + +See http://www.gnustep.org/ - the main web site. + +@node When is GNUstep intended to be available?, What is usable?, Is there a web site?, GNUstep General Information +@subsection When is GNUstep intended to be available? + +It's usable now (for an experienced developer). Releases are made +about every six months. However, if you are a serious developer, it's probably +best to use the latest snapshots. See the GNUstep web site for a release +schedule. + +@node What is usable?, , When is GNUstep intended to be available?, GNUstep General Information +@subsection What is usable? + +gstep-make does pretty much what the makefiles in NeXTstep do. +gstep-base (Foundation) stuff should work fine for almost all projects. +gstep-db is only EOF-1.0 compatible but should work ok. +gstep-gui (AppKit) is usable with the xgps backend, and +you would probably have to fix some things in the gui library. +Cut-and-paste works, services work, drag-and-drop works, +the NSText classes partially work. gstep-xgps +basic functionality is quite usable. gstep-xdps is mostly usable. +DGS (Display Ghostscript) is usable but slow. + + +@c **************************************************************** +@c Compiling +@node Compiling and Developing, GNU Objective C Compiler and Objective C Runtime Library, GNUstep General Information, Top +@section Compiling and Developing + +@menu +* Can I run NeXT OPENSTEP or Apple Rhapsody programs on GNUstep?:: +* Is it easy to port OPENSTEP and Rhapsody programs to GNUstep?:: +* Is there an Interface Builder for GNUstep?:: +* Can I use my original NIB files?:: +* Will code without NIB files work?:: +* Is GNUstep following Apple's Changes to OpenStep?:: +* Do we have to have the NeXTstep look and feel?:: +* Can one use the hybrid "Objective-C++":: +* Is there a plan to support Java/YellowBox Bindings?:: +* What if I compile GNUstep under OPENSTEP/MacOS X Server?:: +* How can I help with GNUstep?:: +* How do I start writing code?:: +* How do I start writing documentation?:: +* How do I update the task list?:: +* How do I start writing tests?:: +* How do I start writing applications?:: +* How can I help with the GNUstep website?:: +* How do I compile GNUstep on my machine? :: +* Are there any precompiled packages available?:: +* I get an error compiling mframe.m in gnustep-base:: +@end menu + +@node Can I run NeXT OPENSTEP or Apple Rhapsody programs on GNUstep?, Is it easy to port OPENSTEP and Rhapsody programs to GNUstep?, Compiling and Developing, Compiling and Developing +@subsection Can I run NeXT OPENSTEP or Apple Rhapsody programs on GNUstep? + +You can't run these programs on GNUstep, but if you have the source +code for the programs, you should be able to port them to GNUstep and +compile them. Whether or not you will be able to run them depends on how +complete GNUstep is at the time. + +@node Is it easy to port OPENSTEP and Rhapsody programs to GNUstep?, Is there an Interface Builder for GNUstep?, Can I run NeXT OPENSTEP or Apple Rhapsody programs on GNUstep?, Compiling and Developing +@subsection Is it easy to port OPENSTEP and Rhapsody programs to GNUstep? + +It is probably easy for simple programs. You'll have to use nfmake +@url{http://karl.nfox.com} to translate the PB.prject file to GNUstep +Makefiles, or rewrite the Makefiles yourself. You will also have to +translate the NIB files (if there are any) to GNUstep model files using +the nib2gmodel program (from @url{ftp://ftp.gnustep.org/pub/gnustep/dev-apps}). + +@node Is there an Interface Builder for GNUstep?, Can I use my original NIB files?, Is it easy to port OPENSTEP and Rhapsody programs to GNUstep?, Compiling and Developing +@subsection Is there an Interface Builder for GNUstep? + +There is an Interface Builder for GNUstep called Gorm, but it is +in alpha release, so it may not work perfectly. +You can get it from the GNUstep CVS repository (cvs -z3 checkout Gorm). +The Project Manager ProjectCenter is also new. + +@node Can I use my original NIB files?, Will code without NIB files work?, Is there an Interface Builder for GNUstep?, Compiling and Developing +@subsection Can I use my original NIB files? + + No - NeXT/Apple never documented their nib format, so GNUstep +supports both the 'gmodel' format (which stores information as text +(property-lists) and can therefore be edited 'by hand') and binary +archive format (which can be edited by Gorm). +There IS a conversion tool that can be compiled under OPENSTEP to convert +OPENSTEP nib files to GNUstep gmodel files. + +@node Will code without NIB files work?, Is GNUstep following Apple's Changes to OpenStep?, Can I use my original NIB files?, Compiling and Developing +@subsection Will code without NIB files work? + + Well, GNUstep implements the OpenStep API, not the old NeXTstep +API but, Yes - once the gui library is complete, OpenStep or MacOS-X +code should work without translation under GNUstep. + +@node Is GNUstep following Apple's Changes to OpenStep?, Do we have to have the NeXTstep look and feel?, Will code without NIB files work?, Compiling and Developing +@subsection Is GNUstep following Apple's Changes to OpenStep? + +Yes - gstep-base already contains the documented changes in the +Foundation library. GNUstep aims to be compatible with both the +OpenStep specification and with MacOS-X It should be easy to write +an application that compiles cleanly under both GNUstep and Yellow +Box. + +@node Do we have to have the NeXTstep look and feel?, Can one use the hybrid "Objective-C++", Is GNUstep following Apple's Changes to OpenStep?, Compiling and Developing +@subsection Do we have to have the NeXTstep look and feel? + +Gnustep is aiming for something like the NeXTstep-3.3 look and +feel This is mostly determined by the gui backend library. In the +case of the two existing backends (xdps and xgps), both are designed +to look like NeXTstep/OPENSTEP. If someone wants to write a backend +with a different look, they can. This would only be a few man-months +work. + +@node Can one use the hybrid "Objective-C++", Is there a plan to support Java/YellowBox Bindings?, Do we have to have the NeXTstep look and feel?, Compiling and Developing +@subsection Can one use the hybrid "Objective-C++" +that one could on the NeXT? + + No - at present the GNU compiler (gcc or egcs) does not support +"Objective-C++" There are no specific plans to make it do so, but +any volunteers to do it would be welcome. + +@node Is there a plan to support Java/YellowBox Bindings?, What if I compile GNUstep under OPENSTEP/MacOS X Server?, Can one use the hybrid "Objective-C++", Compiling and Developing +@subsection Is there a plan to support the Java/YellowBox Bindings? + +Yes. The GNustep Java library/bridge called JIGS is available now. JIGS +is a free (LGPL) Java Interface for GNUstep; it can automatically wrap +Objective-C libraries based on GNUstep making them accessible directly +to the Java programmer as if they were Java libraries. As a side effect, +it is also possible to use the whole engine in the reverse way: JIGS +provides a high level API to allow Objective-C programmers to start java +virtual machines inside GNUstep Objective-C code and access java objects +in the java virtual machine transparently, as if they were objective-C +objects. + +@node What if I compile GNUstep under OPENSTEP/MacOS X Server?, How can I help with GNUstep?, Is there a plan to support Java/YellowBox Bindings?, Compiling and Developing +@subsection What if I compile GNUstep under OPENSTEP/MacOS X Server? + + No - GNUstep uses the X-windows display postscript extension +- the interface to that is not the same as the interface to the +OPENSTEP/MacOS-X windows server. While someone could write a +backend library to provide the interface, nobody has bothered to +date. + +Also - there is no known recent port to OPENSTEP of the base library. + +@node How can I help with GNUstep?, How do I start writing code?, What if I compile GNUstep under OPENSTEP/MacOS X Server?, Compiling and Developing +@subsection How can I help with GNUstep? + + 1. Write/debug library code 2. Write documentation 3. Update +the TODO list and library headers 4. Write applications + +Some general advice - + +Let people know what you are doing. Break your project up into +the smallest units you can. Feed back frequent updates to the +maintainers. Ask questions in the discussion mailing list. + +Do remember that any changes beyond a few lines of code (or +documentation) require a disclaimer or copyright assignment to the +Free Software Foundation before they can be incorporated into the +project. Get in touch with the maintainer of the library you are +working on about this. + +Don't start with large-scale reorganisation of anything - instead, +get a general idea in mind of what you want to do, and proceed as +much as possible with incremental changes that don't break anything +- that way you can make those incremental changes available to the +rest of the community at frequent intervals. + +Don't be afraid to give up - there is no shame in finding out that +you have take on too large/complex a project. It's much better to +'resign' and take on a smaller job than to just stop without telling +anyone. + + +@node How do I start writing code?, How do I start writing documentation?, How can I help with GNUstep?, Compiling and Developing +@subsection How do I start writing code? + + There is plenty of unimplemented stuff in the gui library and +backend libraries that volunteers can work on - just browse through +the code and see if it conforms to the documentation. + +Specific tasks are noted in the developers section on the www.gnustep.org +website. + +Once you have coded something, you could always write a testcase +and documentation for it :-) + +@node How do I start writing documentation?, How do I update the task list?, How do I start writing code?, Compiling and Developing +@subsection How do I start writing documentation? + +Our documentation format is called gsdoc, which is an SGML format +for Objective-C documentation in the same vein as XML. We are also trying +to use Autodoc to self document source code. The gsdoc translator is +included with the base library. + +Newcomers could write documentation for individual classes by +comparing the OpenStep specification, the MacOS-X documentation, +and the GNUstep source. Documentation should clearly note where +individual methods are specific to OpenStep, MacOS-X or are GNustep +extensions. + +More experienced people could write documentation on general +programming topics, and tutorials for new users. + +Anyone willing to write documentation, either tutorials for using +GNUstep, or reference documentation for individual classes, should +either write it in gsdoc or as plain ascii text for someone else to +format into gsdoc. + +GNUstep documentation should have copyright assigned to the Free +Software Foundation. + +@node How do I update the task list?, How do I start writing tests?, How do I start writing documentation?, Compiling and Developing +@subsection How do I update the task list? + + The task list (@url{http://www.gnustep.org/developers/tasks.html}) is +supposed to tell people what jobs are waiting to be done. + +One job of major importance that pretty much anyone can do is to +look for jobs to add to the task list. In the case of methods from +the OpenStep specification or the MacOS-X documentation not being +present in the GNustep libraries, it is also helpful to add the +method prototypes to the library header files. + +At the moment, send changes to Adam Fedor @email{fedor@@gnu.org} or Richard +Frith-Macdonald @email{richard@@brainstorm.co.uk} + +We are hoping to have a system where people can update the list +directly. + +A beginner can look through the MacOS-X documentation, the OpenStep +specification and the GNUstep source and contribute TODO items. + +If a class or method is in MacOS-X and OpenStep but is not in +GNUstep - it's a high priority TODO and should at least be added +to the GNUstep headers and a dummy version added to the source with +a FIXME comment. + +If a class or method is in MacOS-X but not OpenStep or GNUstep - +it's a low priority TODO. It should be added to the GNUstep headers +bracketed in @code{#ifndef STRICT_OPENSTEP} + +If a class or method is in OpenStep but not in MacOS-X or GNUstep +- it's a low priority TODO. It should be added to the GNUstep +headers bracketed in @code{#ifndef STRICT_MACOS_X} + +There are a couple of people working on this already, so it's a +good idea to get in touch with Adam or Richard to coordinate efforts. + +@node How do I start writing tests?, How do I start writing applications?, How do I update the task list?, Compiling and Developing +@subsection How do I start writing tests? + + You can write testcases - where the libraries fail tests, you +could either fix the problem, or add it to the task list. + +To write testcases, you need to use anonymous CVS to install the +latest gstep-core snapshot you can find. Then checkout the 'tests' +module from CVS. In the 'tests' directory, you will find a +regression testing framework for gstep-base. +In order to use this you will also need a recent (v 1.3.2 or later) copy of +Guile (you can get this from a GNU ftp site) and will need to hacke checked +out, built, and installed the 'guile' package from the GNUstep CVS repository. + +At present, there is no such framework for the gui library - If +you are interested in working on one, contact @email{richard@@brainstorm.co.uk} + +@node How do I start writing applications?, How can I help with the GNUstep website?, How do I start writing tests?, Compiling and Developing +@subsection How do I start writing applications? + + You can either look at the links on the GNUstep website for +applications that have been started, and email their owners to +volunteer to help, or you can start your own project. + +If you are starting your own project, you need to - 1. Get the +latest snapshot of GNUstep and build it to use the 'xgps' or 'xdps' backend +library. 2. Look at +the example applications (particularly Ink.app) in the gstep-examples package +directory as a basis for your work. 3. Be prepared to + a) ask for help on the gnustep-discuss mailing list b) fix bugs + and implement missing functionality in the gui and xgps + libraries. + + +@node How can I help with the GNUstep website?, How do I compile GNUstep on my machine? , How do I start writing applications?, Compiling and Developing +@subsection How can I help with the GNUstep website? + + Talk to Adam Fedor @email{fedor@@gnu.org}, the maintainer. + +The GNUstep website is kept as a CVS module, but the largest portions +of it (the FAQ, the TODO list, and the Documentation) are actually +generated from files in the individual GNUstep packages. + +If you want to update the FAQ or TODO list or documentation - grab +the latest snapshot of the GNUstep core you can find, update it +from the CVS repository, and work with the contents of the appropriate +documentation directory. + +If you want to work on other parts of the website - capture the +pages you want to edit in your web browser (at http://www.gnustep.org). +If you can't do that, you can grab a copy of the website via +anonymous CVS - + +@example +$ CVSROOT=:pserver:anoncvs:@@cvs.net-community.com:/gnustep-www +$ export CVSROOT +$ cvs login (password anoncvs) +$ checkout -z3 www +@end example + +The main task with the website is to figure out which bits are +out-of-date (or wrong) and update/mark-as-outdated as required. + +Current status - + +The 'developers section' of the FAQ is being worked on by +@email{stevensl@@mindspring.net}, and we are looking at rewriting the more +general parts of the FAQ. + +@node How do I compile GNUstep on my machine? , Are there any precompiled packages available?, How can I help with the GNUstep website?, Compiling and Developing +@subsection How do I compile GNUstep on my machine? + +Read the file @file{GNUstep-HOWTO}, which comes with the GNUstep +distribution, and also is available separately on the GNUstep ftp +sites. A PDF version also exists on the web site called +@file{GnustepInstall.pdf}. + +@node Are there any precompiled packages available?, I get an error compiling mframe.m in gnustep-base, How do I compile GNUstep on my machine? , Compiling and Developing +@subsection Are there any precompiled packages available? + +Check @url{http://www.gnustep.org/resources/sources.html} for links +to sites with RPMS, and perhaps in the future, Debian packages. +In some cases. You can check the debian site for preconfigured GNUstep +packages. + +@node I get an error compiling mframe.m in gnustep-base, , Are there any precompiled packages available?, Compiling and Developing +@subsection I get an error compiling mframe.m in gnustep-base. + +This occurs on some GNU/Linux systems. You'll need to change the +optimization level, usually like this: +@example +make OPTFLAG=-O +@end example + +@c ------------------------------------------------------------------- + +@node GNU Objective C Compiler and Objective C Runtime Library, GNUstep Base Library, Compiling and Developing, Top +@section GNU Objective C Compiler and Objective C Runtime Library + +@menu +* What is the Objective C Runtime Library?:: +* Does it allow a mixture of Objective C and C++:: +* Where can I find more information?:: +@end menu + +@node What is the Objective C Runtime Library?, Does it allow a mixture of Objective C and C++, GNU Objective C Compiler and Objective C Runtime Library, GNU Objective C Compiler and Objective C Runtime Library +@subsection What is the Objective C Runtime Library? + +The Objective C Runtime Library provides C functions and data structures +required to execute an Objective C program. + +The GNU Objective C Runtime Library offers everything NeXT's runtime +does, including Categories, Protocols, @samp{+poseAs:}, thread-safety, +class initialization on demand, delayed loading of classes, and +initialization of static instances (such as @@""-style string objects). + +It also has several improvements over NeXT's implementation: + +@itemize @bullet + +@item NeXT's runtime requires an extra function call (objc_msgSend) for +each message that is sent; (the function looks up the receiving +instance's implementation of the method). GNU's implementation is +faster because it does not use an extra function call. Instead, it +inlines a short piece of code that makes two pointer hops into a method +dispatch table; because the code is inlined, it does not incur the +overhead of a function call. + +@item When running in thread-safe mode, NeXT's runtime must aquire a +global mutual exclusion lock every time a message is sent; this is +extremely slow. GNU's runtime, amazingly, sends messages just as fast +in thread-safe mode as it does in single-thread mode---the code path +does not contain even a single extra instruction! The GNU runtime only +needs locks when certainly structures are written, not read; the +structures are written relatively infrequently: only at class +initialization and when @samp{+poseAs:} is called. + +@item GNU's runtime provides ``selector-types'' along with each +selector; NeXT's does not. A selector-type is a string that describes +the C variable types for the method's return and argument values. Among +other uses, selector-types is extrememly helpful for fast distributed +objects implementations, (see GNUstep Base Library Section, below). + +@item Many of the GNU functions have different names than their +corresponding NeXT functions; the GNU names conform to the GNU coding +standards. + +@item GNU's runtime library has a new class heirarchy manipulating +method called @samp{-transmuteClassTo:}. It can change the class of an +instance to a cousin class of the same instance-size. + +@item NeXT's compiler, @samp{cc}, is based on an old version of +@samp{gcc}. GNU's compiler is, of course, the latest version of +@samp{gcc}, and therefore contains all the latest enhancements. + +@end itemize + +@node Does it allow a mixture of Objective C and C++, Where can I find more information?, What is the Objective C Runtime Library?, GNU Objective C Compiler and Objective C Runtime Library +@subsection Does it allow a mixture of Objective C and C++? + +No. Unlike NeXT's @samp{cc}, GNU GCC does not support source files +containing both Objective C and C++. People at Cygnus have mentioned +that they would be willing to do the work---if they were paid for it, of +course. Several people are interested in seeing this happen. Send +email to @samp{discuss-gnustep@@gnu.org} if you are interesting in +pushing this issue, so that the efforts of all those people interested +can be coordinated. + +Also, unlike NeXT's @samp{cc}, GNU GCC does not support the @samp{extern +"Objective-C"} construct. + +@node Where can I find more information?, , Does it allow a mixture of Objective C and C++, GNU Objective C Compiler and Objective C Runtime Library +@subsection Where can I find more information? + +The FAQ associated with the newsgroup @samp{comp.lang.objective-c} +contains more information about GNU Objective C. + +@c ------------- GNU Compiler and Objective C Runtime Library ------- + +@node GNUstep Base Library, GNUstep GUI Library, GNU Objective C Compiler and Objective C Runtime Library, Top +@section GNUstep Base Library + +@menu +* What is the GNUstep Base Library?:: +* What is base's current state of development?:: +* What are the features of GNU Distributed Objects?:: +@end menu + +@node What is the GNUstep Base Library?, What is base's current state of development?, GNUstep Base Library, GNUstep Base Library +@subsection What is the GNUstep Base Library? + +The GNUstep Base Library is a library of general-purpose, non-graphical +Objective C objects. For example, it includes classes for strings, +object collections, byte streams, typed coders, invocations, +notifications, notification dispatchers, moments in time, network ports, +remote object messaging support (distributed objects), event loops, and +random number generators. + +It provides functionality that aims to implement the non-graphical +portion of the OpenStep standard (the Foundation library). + +@node What is base's current state of development?, What are the features of GNU Distributed Objects?, What is the GNUstep Base Library?, GNUstep Base Library +@subsection What is its current state of development? + +It is about 98 percent of the way to having all the OpenStep classes (and +the later OPENSTEP/Rhaspody classes) fully implemented. +Normal work can already be done using the library since the +missing 2 percent are the least-often-used features or are simply not +up to date with the latest MacOS-X spec. +Over 60,000 lines of code have already been written. + +@node What are the features of GNU Distributed Objects?, , What is base's current state of development?, GNUstep Base Library +@subsection What are the features of GNU Distributed Objects? + +GNU Distributed Objects has many of the features of other distributed +objects implementations, but, since it is free software, it can be +ported to platforms for which other distributed objects implementations +are not available. + +[NOTE: The GNU distributed object facilities have the same ease-of-use +as NeXT's; be warned, however, that they are not compatible with each +other. They have different class heirarchies, different instance +variables, different method names, different implementation strategies +and different network message formats. You cannot communicate with a +NeXT NSConnection using a GNU Connection. + +Here are some differences between GNU distributed objects and NeXT's +distributed objects: NeXT NSDistantObject asks it's remote +target for the method encoding types and caches the results; GNU +NSDistantObject gets the types directly from the local GNU "typed selector" +mechanism if the information is known locally and only queries the remote +target or caching encoding types when using a method that is not known to +the local process. The NSProxy for the remote root object always has name 0 +and, once set, you cannot change the root object of a NSConnection; the GNU +Proxy for the remote root object has a target address value just like +all other Proxy's, and you can change the root object as many times as +you like. ]. + +@c --------------------------GNUstep Base Library---------------------- + +@node GNUstep GUI Library, GNUstep DisplayGhostScript Server, GNUstep Base Library, Top +@section GNUstep GUI Library + +@menu +* What is the GUI Library?:: +* Explain the organization of the front- and back-ends:: +* What is the current state of development of the front-end?:: +* What is the current state of development of the X/DPS back-end?:: +@end menu + +@node What is the GUI Library?, Explain the organization of the front- and back-ends, GNUstep GUI Library, GNUstep GUI Library +@subsection What is the GUI Library? + +The GNUstep GUI Library is a library of objects useful for writing +graphical applications. For example, it includes classes for drawing +and manipulating graphics objects on the screen: windows, menus, +buttons, sliders, text fields, and events. There are also many +peripheral classes that offer operating-system-independent interfaces to +images, cursors, colors, fonts, pasteboards, printing. There are also +workspace support classes such as data links, open/save panels, +context-dependent help, spell checking. + +It provides functionality that aims to implement the @samp{AppKit} +portion of the OpenStep standard. However the implementation has +been written to take advantage of GNUstep enhancements wherever possible. + + +@node Explain the organization of the front- and back-ends, What is the current state of development of the front-end?, What is the GUI Library?, GNUstep GUI Library +@subsection Explain the organization of the front- and back-ends + +The GNUstep GUI Library is divided into a front- and back-end. The +front-end contains the majority of implementation, but leaves out the +low-level drawing and event code. A back-end can override whatever +methods necessary in order to implement low-level drawing event +receiving. Different back-ends will make GNUstep available on various +platforms. The default GNU back-end will run on top of X Windows and +the DisplayGhostScript Server. Other back-ends could allow GNUstep to +run on OpenGL, OS/2, and WIN32 graphics/event platforms. Much work +will be saved by this clean separation between front- and back-end, +because it allows different platforms to share the large amount of +front-end code. + +@node What is the current state of development of the front-end?, What is the current state of development of the X/DPS back-end?, Explain the organization of the front- and back-ends, GNUstep GUI Library +@subsection What is the current state of development of the front-end? + +Many of the classes are well implemented, if not thouroughly tested. +See the GNUstep web sites and read status information contained in the +distribution for the most up-to-date information. + +@node What is the current state of development of the X/DPS back-end?, , What is the current state of development of the front-end?, GNUstep GUI Library +@subsection What is the current state of development of the X/DPS back-end? + +It works, but is slow and buggy. A lot of work could be done. + +@c ------------------------- GNUstep GUI Library ----------------------- + +@node GNUstep DisplayGhostScript Server, , GNUstep GUI Library, Top +@section GNUstep DisplayGhostScript Server + +@menu +* What is the Display Ghostscript Server?:: +* What is DGSs current state of development?:: +* What is the relationship between the Display Ghostscript Server and X Windows?:: +@end menu + +@node What is the Display Ghostscript Server?, What is DGSs current state of development?, GNUstep DisplayGhostScript Server, GNUstep DisplayGhostScript Server +@subsection What is the Display Ghostscript Server? + +It is a free implementation of a Display PostScript server based on the +ghostscript program by Aladdin software. + +@node What is DGSs current state of development?, What is the relationship between the Display Ghostscript Server and X Windows?, What is the Display Ghostscript Server?, GNUstep DisplayGhostScript Server +@subsection What is its current state of development? + +GNU contracted with Aladdin software to add some key features to +ghostscript so it could be used as a DPS server. This work has mostly +been done, althought Aladdin did not completely finish the work that they +were contracted for. DGS works fairly well with a single context and +will soon work with multiple contexts. Alpha channel and compositing +currently doesn't work, but should before the end of 2000 (It's already +been fixed in Ghostscript, just not released). + +@node What is the relationship between the Display Ghostscript Server and X Windows?, , What is DGSs current state of development?, GNUstep DisplayGhostScript Server +@subsection What is the relationship between the Display Ghostscript Server and X Windows? + +Display Ghostscript runs on top of X Windows. + +@c ------------------ GNUstep DisplayGhostScript Server --------------- + + + +@format +All trademarks mentioned on in this FAQ belong to their owners. +@end format + +@bye +\bye diff --git a/Documentation/gnustep-howto.texi b/Documentation/gnustep-howto.texi new file mode 100644 index 00000000..16b04a6b --- /dev/null +++ b/Documentation/gnustep-howto.texi @@ -0,0 +1,472 @@ +\input texinfo @c -*-texinfo-*- +@c GNUstep installation instructions +@c %**start of header +@setfilename gnustep-howto.info +@settitle GNUstep HOWTO +@c %**end of header +@set HOWTO +@setcontentsaftertitlepage +@smallbook + +@titlepage +@title GNUstep HOWTO +@subtitle Installing the GNUstep developement system + +@vskip 0pt plus 1filll +@emph{This document explains how to build the different components of +the GNUstep core libraries.} + +Last Update: @today{} + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1996 - 2001 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation. + +@end titlepage + +@ifinfo +@format + GNUstep HOWTO + ************* + + Last Update: @today{} + + This document explains how to build the different components of the + GNUstep core libraries. + + Copyright (C) 1996 - 2001 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 or + any later version published by the Free Software Foundation. +@end format + +@end ifinfo + +@include version.texi + +@node Top, Introduction, (dir), (dir) + +@menu +* Introduction:: +* Summary:: +* Compiling and Installing:: +* Additional Installation:: +* Tools and Applications:: +* Machine Specific:: +* Anonymous CVS:: +* Other:: +@end menu + +@node Introduction, Summary, Top, Top +@chapter Introduction + +This document explains how to build the GNUstep core libraries. The core +libraries, along with associated tools and other files provide +everything necessary for a working GNUstep system. + +In order to easily compile and debug GNUstep projects, you will need the +GNU Objective-C compiler @samp{GCC} as well as various other GNU packages. + +You will need at least 80Mb of hard disk space (150Mb prefered) in order +to compile the GNUstep core libraries. + +@node Summary, Compiling and Installing, Introduction, Top +@chapter Summary + +In order to compile the libraries, you need to compile and install +the following packages first (if you don't already have them): + +@itemize @bullet +@item gcc (Version 2.8.0 or greater) +@item GNU make (Version 3.75 or greater) +@item The TIFF library (libtiff) (Version 3.4beta36 or greater) +@end itemize + +After installing these packages, get the following individual packages: + +@itemize @bullet +@item gnustep-make +@item gnustep-base +@item gnustep-gui +@item gnustep-xdps +@item gnustep-xgps +@end itemize + +See @url{http://www.gnustep.org} for information on where to get these +packages. Only one of gnustep-xgps or gnustep-xdps is required. We +currently recommend gnustep-xgps. Other packages you may need to get +depending on the type of system you are using, include: + +@table @samp +@item WindowMaker (Version >= 0.62) +GNUstep and WindowMaker work together to provide a consistant interface. +Although it is not required, GNUstep will work much better if you use it +with the WindowMaker window manager. In addition, WindowMaker includes some +functionality that GNUstep uses that would otherwise not be available. +Get WindowMaker from @url{http://www.windowmaker.org}. + +@item DGS, the XFree86 DPS extension, or Adobe DPS +If you want to use the features of a Display Postscript +(DPS)backend. Note that it is not required since you can use the XGPS +backend that is Xlib based. Note that the DPS backend is also still +experimental and not recommended. DPS can be obtained from the +following locations: + +@itemize @bullet +@item DGS client/server, @url{ftp://ftp.gnustep.org/pub/gnustep/dgs} +@item XFree86 DPS, @url{http://dps.sourceforge.net/} +@item Adobe DPS, (contact your OS distributor) +@end itemize + +@item PCThreads +For GNU/Linux systems on Intel x86 processors. PCThreads is +no longer necessary (and should not be used) on GNU/Linux systems with +glibc version 2, such as Debian 2.0 and RedHat 5.x and greater. + +@item GDB and Objective-C patch +GDB can be obtained from @url{ftp://ftp.gnu.org/gnu/gdb}. The patch to +make it work better with GNUstep can be obtained from +@url{ftp://ftp.gnustep.org/pub/gnustep} + +@item libxml +The libxml library (Version 2) is used to translate some of the +documentation for GNUstep and to provide suport for MacOS-X compatible +XML-based property-lists. It is recommended but not currently required. + +@item openssl +The openssl library is used to provide support for https connections by +the NSURL and HSURLHandle classes. +It is recommended but not currently required. + +@item libiconv +Unicode support functions (iconv) come with glibc version 2.1 or greater. If +you don't have this, you can get the separate libiconv library +from @url{ http://clisp.cons.org/~haible/packages-libiconv.html}. However, +neither one is required to use GNUstep. + +@item ffcall libraries +This is a library that provides stack frame handling for NSInvocation +and NSConnection. This library is highly recommended. The previous +builtin method for stack frame handling is no longer supported and +may be removed in the future. + +@item libobjc library snapshot (for gcc version <= 2.95.2) +This is a special version of the Objective-C runtime that include several +bug fixes and features that have not been officially released yet. +It is available at @url{ftp://ftp.gnustep.org/pub/gnustep/libs} which +compiles using the GNUstep Makefile package (so you don't have to get the +entire gcc dist). Make sure to set the THREADING variable in the GNUmakefile. +It might also be best to compile the library static (make shared=no) and +just copy to the place where the gcc libobjc library is (type gcc -v to +get this location). +@end table + +@node Compiling and Installing, Additional Installation, Summary, Top +@chapter Compiling and Installing the packages + +Make sure you install all the previously mentioned libraries first +before configuring and building GNUstep (Except you need to install +libobjc after installing gnustep-make, unless your installing it as part +of gcc). + +Note: you will need to be able to install packages as root (at least +the base library) for applications to work correctly. + +For installation on MinGW systems, read the README.MinGW file in the +make package. + +@menu +* DPS System:: +* Core Package:: +@end menu + +@node DPS System, Core Package, Compiling and Installing, Compiling and Installing +@section Using a Display Postscript System + +Install a Display PostScript system if you want to use the XDPS backend. +You do not need it if you want to use the XGPS backend. +Some systems, like Sun Microcomputers(TM) already have a DPS system installed. +Linux/GNU systems need to use a free implementation of DPS (described in +the Introduction.) + +If you are installing DGS, follow the installation instructions included with +the DGS package. If you are installing the XFree86 DPS extension, follow the +instructions included with that package (and note that you need to be +running XFree86 version 4.0 or greater). + +@node Core Package, , DPS System, Compiling and Installing +@section Installing the Core Libraries + +The GNUstep packages uses the Autoconf mechanism for +configuration; it checks some host capabilties which are used by +all GNUstep software. To configure just type: + +@example +./configure +@end example + +The GNUstep makefile package needs a root directory. If the +GNUSTEP_SYSTEM_ROOT environment variable is set then configure will +use its value as the root directory. You can also specify the root +directory when you run configure with the prefix paramter; the +following command makes /usr/local/GNUstep the root directory: + +@example +./configure --prefix=/usr/local/GNUstep +@end example + +If you do not have the GNUSTEP_SYSTEM_ROOT environment variable set +and you do not specify a root directory when running configure, then +configure will use /usr/GNUstep as the default root directory. + +@menu +* Alternate Library Setup:: +* Individual Packages:: +@end menu + +@node Alternate Library Setup, Individual Packages, Core Package, Core Package +@subsection Alternate Library Setup + +You can specify compilation of alternate libraries by using the +--with-library-combo option: + +@example +./configure --with-library-combo=gnu-gnu-gnu-xdps +@end example + +to compile with the xdps library rather than the default xgps backend. +IMPORTANT: The xdps backend is still experimental. Do not use it unless +you are willing to deal with PostScript problems and other bugs. + +Read the installation instructions in the Makefile package (make) for more +installation options. Make sure you use the same +configuration options when configuring each GNUstep library. + +@node Individual Packages, , Alternate Library Setup, Core Package +@subsection Building the Package + +To build the individual packages, use the familiar set of commands for +each pacakge: + +@example +./configure +make +make install +@end example + +Start with the Makefile Pacakge (gnustep-make), then do gnustep-base, +gnustep-gui and finally gnustep-xgps (or gnustep-xdps). After installing +gnustep-make you need to execute GNUstep's shell configuration +script, as follows: + +@example + . /usr/GNUstep/System/Makefiles/GNUstep.sh +@end example + +before proceeding any further. + +NOTE: If you are trying to install the packages without root permission, +you need to change one thing in the base library. Edit the file +gnustep-base/Tools/gdomap.h and uncomment the last line. + +@node Additional Installation, Tools and Applications, Compiling and Installing, Top +@chapter Additional Installation + +Add the shell script @file{GNUstep.sh} located in the Makefile +package to your shell startup file (such as @file{.profile}). For instance: + +@example +GNUSTEP_SYSTEM_ROOT=/usr/GNUstep +export GNUSTEP_SYSTEM_ROOT +. $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh +@end example + +in your @file{.profile} file will work (Note the period at the beginning +of the line). It defines environment variables that are needed to find +GNUstep files and executables. Users of csh need to use the +@file{GNUstep.csh} script. Read the make package @file{README} for more +info. Some systems, like GNU/Linux have an @file{/etc/profile.d} +directory where scripts can be executed automatically. If you want to +set up GNUstep for every user on your system, you can try +copying/linking the @file{GNUstep.sh} there. For csh or tcsh, try + +@example +setenv GNUSTEP_SYSTEM_ROOT /usr/GNUstep +source $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.csh +@end example + +Set up your home GNUstep directory. This is where user defaults are +kept, and in the future, other files may be kept there. + +@example +cd +mkdir GNUstep +@end example + +Next, set your local time zone. There are four ways to do this, pick +one (see @file{$GNUSTEP_SYSTEM_ROOT/Libraries/Resources/NSTimeZones/zones} for typical time zones): + +@enumerate +@item Use the defaults utility to set ``Local Time Zone'' to your local +time zone (defaults is installed with GNUstep in the Tools directory). Type +something like ``defaults write NSGlobalDomain "Local Time Zone" GB''. + +@item Set the @var{GNUSTEP_TZ} environment variable. + +@item Create the file @file{$GNUSTEP_SYSTEM_ROOT/Libraries/Resources/NSTimeZones/localtime} with the name of the local time zone in it. + +@item Set the @var{TZ} environment variable (this may conflict with other +software on your system though). +@end enumerate + +If you are using a built-in DPS server, you may need to set the PSRESOURCEPATH +environment variable (on Solaris, it's set to @file{/usr/openwin/lib/X11}). + +Set up your system to execute some GNUstep deamons. If you don't do this, they will be started automatically when you run your first GNUstep app: + +@itemize @bullet +@item gdomap - Put this in a system startup file, like @file{/etc/rc.local} or @file{/etc/rc.d/rc.local} (customize for your system) +@example +GNUSTEP_SYSTEM_ROOT=/usr/GNUstep +if [ -f $GNUSTEP_SYSTEM_ROOT/Tools/powerpc/linux-gnu/gdomap ]; then + $GNUSTEP_SYSTEM_ROOT/Tools/powerpc/linux-gnu/gdomap +fi +@end example +@item gdnc - Put this after executing @file{GNUstep.sh} in your local .profile +@item gpbs - Put this after executing @file{GNUstep.sh} in your local .profile +@end itemize + +@example +if [ `gdomap -L GDNCServer | grep -c Found` == '0' ]; then + echo "Starting GNUstep services..." + gdnc + gpbs +fi +@end example + + +@node Tools and Applications, Machine Specific, Additional Installation, Top +@chapter Test Tools and Applications + +Test programs for the base library are in @file{base/Testing}. Example +applications are located in the gstep-examples package. To make these, +just uncompress and untar this package, cd to the appropriate +directory, and type make. Generally you will need to install GNUstep +first before doing this. + +To run the examples. Use the openapp utility that is part of the GNUstep +makefile package (and stored in +@file{$GNUSTEP_SYSTEM_ROOT/Tools}). Usage is: + +@example +openapp [--library-combo=...] application [additional arguments to app] +@end example + +Good Luck! + +@node Machine Specific, Anonymous CVS, Tools and Applications, Top +@chapter Machine Specific Instructions + +@include machines.texi + + +@node Anonymous CVS, Other, Machine Specific, Top +@chapter Getting Libraries via Anonymous CVS + + If you didn't get one of the snapshots, or if you want to be sure +to stay on the bleading edge, then you should get the core via CVS: + +The quick and painless CVS tutorial (by michael hanni (slightly modified) + + First, set the CVSROOT environment variable. If you are using +bash/sh you can do something like this at the prompt: +@example +export CVSROOT=":pserver:anoncvs@@cvs.net-community.com:/gnustep" +@end example + + Second, if this is the first time loging into the CVS server: +@example +cvs login +@end example + + You should get a password prompt soon after: +@example +(Logging in to anoncvs@@cvs.net-community.com) +CVS password: +@end example + + Enter the password @samp{anoncvs}. This should return you to your +prompt. From here you can checkout any module in the CVS server you +like. To checkout a module you do this: +@example +cvs -z3 checkout modulename +@end example + + The -z3 merely tells the cvs server to compess everything to a +certain compression level before it sends it to you. + + If you haven't already done so, change to the directory, where you +want the source to reside. + + Next, you want to get the whole core, so you do: +@example +cvs -z3 checkout core +@end example + + After you have checked out the source you can compile it as +usual. To update the source, go into the directory of the source tree +you want to update, for example, go into 'xgps', and type: + +@example +cvs -z3 update -Pd +@end example + + You don't have to re-checkout after you have the source, just update! +Also try @samp{cvs checkout -c} to get a list of available modules. + +@node Other, , Anonymous CVS, Top +@chapter Other Instructions + +@menu +* Better Debugging:: +@end menu + +@node Better Debugging, , Other, Other +@section Better debugging with Objective-C runtime + +Normally, the Objective-C runtime is compiled with debugging information, +which actually makes debugging of user apps frustrating because stepping +into a method call will actually cause gdb to step into the internal +Objective-C method call mechanism, which you don't want most of the time. + +The way to avoid this is to compile the Objective-C runtime library without +debugging information. Here's how: + +@example +cd egcs-build-directory/gcc +rm -f objc/*.o +make CFLAGS=-O2 libobjc.a +cp libobjc.a your-egcs-installation-dir +@end example + + + +@chapter Acknowledgements + +@format + Authors: Adam Fedor , + Pascal Forget , + Ovidiu Predescu , + Camille Troillard + Richard Frith-MacDonald + + This file is part of GNUstep. +@end format + +@bye +\bye diff --git a/Documentation/machines.texi b/Documentation/machines.texi new file mode 100644 index 00000000..7b42783f --- /dev/null +++ b/Documentation/machines.texi @@ -0,0 +1,587 @@ +@c \input texinfo @c -*-texinfo-*- +@setfilename machines.info +@ifclear HOWTO +@c Machine Specific, Debian/DEC-Alpha, , (DIR) +@node Machine Specific, Debian/DEC-Alpha, , (DIR) +@chapter Machines +@end ifclear + +Below is a list of machines that people have attempted to compile +GNUstep on. GNUstep compiles with little or no trouble on many of the +more popular operating systems. Some machines marked with +@emph{Unstable} may have some trouble or may not work at all. + +@menu +* Debian/DEC-Alpha:: +* FreeBSD 3.x:: +* FreeBSD 2.x:: +* GNU-Linux/Intel:: +* GNU-Linux/PowerPC 4:: +* GNU-Linux/PowerPC 5:: +* Irix 6.4/MIPS:: +* MkLinux/PowerPC:: +* NetBSD:: +* Netwinder:: +* OpenBSD 2.x:: +* OSF/Alpha:: +* Solaris 2.5.1/Sparc:: +* Solaris 2.6/Sparc:: +* Solaris 2.7/Intel:: +* Suse 6.x/Intel:: +* Suse 7.x/Intel:: +* Unixware-2.1.3/Intel:: +* Windows with CYGWIN:: +@end menu + +A recommended compiler is listed for each machine, if known. You should try +to use the recommended compiler for compiling GNUstep, as GNUstep is quite +complex and tends provoke a lot of errors in some compilers. Even versions +newer than the listed compiler may not work, so don't just get the latest +version of a compiler expecting it to be better than previous versions. + +If you have compiled GNUstep on a specific machine, please send information +about what you needed and any special instructions needed to the +GNUstep maintainer @email{gnustep-maintainers@@gnu.org}. + +If your having mysterious trouble with a machine, try compiling GNUstep without optimization. Particularly in the newer GCC compilers, optimization can break +some code. The easiest way to do this is when +configuring: @samp{CFLAGS="" ./configure}. Or @samp{make OPTFLAG=""}. + +@c ----------------------------------------- +@node Debian/DEC-Alpha, FreeBSD 3.x, Machine Specific, Machine Specific +@section Debian/DEC-Alpha + +@table @samp +@item Recommended compiler +Unknown + +@item Extra libs needed +Unknown + +@item Special Instructions +Unknown +@end table + +@c ----------------------------------------- +@node FreeBSD 3.x, FreeBSD 2.x, Debian/DEC-Alpha, Machine Specific +@section FreeBSD 3.x +@c contact: David Lazaro + +Compiles "out of the box" on FreeBSD 3.4. + +@table @samp +@item Recommended compiler +gcc 2.95.2 + +@item Extra libs needed +Unknown + +@item Special Instructions + +You need to use gmake not make to compile the GNUstep packages. A special +port of gdb can be used with the Objective-C patches from +@url{ftp://ftp.pcnet.com/users/eischen/FreeBSD/gdb-4.17-port.tar.gz} + +The best compiler for GNUstep is the latest release of the GNU Compiler +Collection (GCC). You can find it at @url{http://egcs.cygnus.com/}. + +If you want to use the native POSIX threads support from @file{libc_r} pass +@code{--enable-threads=posix} to configure. This is the recommended option as +this is the FreeBSD threads package that gives the best results --with others +you may be unable to run some examples like @file{diningPhilosophers}. + +The whole compilation process can fail if you have another threads library +installed so watch out for installed packages like @file{pth} and such. +Besides the support for libc_r, GNUstep will also look for @file{pth} and +@file{pcthreads}, so if you have installed them and they aren't detected +prepare to write a nice bug report. + +This can be done more much easily by using the port version. Just @code{cd} +to @file{/usr/ports/lang/egcs} and do a @code{"make WANT_THREADS=yes install"}. +Easy. + +If configure cannot find tiff.h or the tiff library and you have it installed +in a non-standard place (even @file{/usr/local}), you may need to pass these +flags to configure: @code{CFLAGS="-I/usr/local/include"} and +@code{LDFLAGS="-L/usr/local/lib"}. + +@end table + +@c ----------------------------------------- +@node FreeBSD 2.x, GNU-Linux/Intel, FreeBSD 3.x, Machine Specific +@section FreeBSD 2.x (@emph{Unstable!}) + +@table @samp +@item Recommended compiler +gcc 2.8.x + +@item Extra libs needed +Unknown + +@item Special Instructions +Only static libraries work on this system. +Use /stand/sysinstall to install these packages if you have not +already done so: + +@format +gmake (GNU make) +gcc 2.8.x +@end format + +Seems to compile ok, but some tests crash. Possibly due to a +performace 'hack' in base. Might be a good idea to upgrade to FreeBSD 3.x. +You need to use gmake not make to compile the GNUstep packages. + +@end table + +@c ----------------------------------------- +@node GNU-Linux/Intel, GNU-Linux/PowerPC 4, FreeBSD 2.x, Machine Specific +@section GNU-Linux/Intel (RedHat 5.x, 6.x, and 7.0) + +@table @samp +@item Recommended compiler +With 5.x, the egcs compiler that comes with RedHat. Later versions may +have gcc installed, although 7.0 comes with a snapshot of gcc (called +2.96) which is unsuitable for compiling Objective-C code. For 7.0 you +should install the egcs compatibility packages (or an official gcc release). + +@item Extra libs needed +Unknown + +@item Special Instructions +Make sure you have a decent version of the compiler. Try @samp{cc -v} +or @samp{gcc -v} to get the version of the compiler. +With 5.x, make sure you set CC=egcs before configuring, as +in: + +@example +export CC=egcs +configure .... +@end example + +Since RedHat 5.x also comes standard with an old version of gcc. + +On RedHat 7.0, configure like this +@example +CC=egcs LDFLAGS="-u shmctl@@GLIBC_2.2 -L/lib -lc -u getpwuid_r@@GLIBC_2.1.2 +-L/lib -lc -u getpwnam_r@@GLIBC_2.1.2 -L/lib -lc" ./configure +@end example +@end table + +@c ----------------------------------------- +@node GNU-Linux/PowerPC 4, GNU-Linux/PowerPC 5, GNU-Linux/Intel, Machine Specific +@section GNU-Linux/PowerPC (LinuxPPC 4.x) + +@table @samp +@item Recommended compiler +egcs-2.90.25 980302 (egcs-1.0.2 prerelease). +glibc-0.961212-1h. +gdb: 4.16.97. + +@item Extra libs needed +None. + +@item Special Instructions +egcs-1.1.2 does NOT work. +@end table + +@c ----------------------------------------- +@node GNU-Linux/PowerPC 5, Irix 6.4/MIPS, GNU-Linux/PowerPC 4, Machine Specific +@section GNU-Linux/PowerPC (LinuxPPC 5.x) + +@table @samp +@item Recommended compiler +egcs-1.1.2 (default compiler), or +gcc-2.95 + +@item Extra libs needed +None. + +@item Special Instructions +You need to compile without optimization or the compiler will not +be able to compile several files (CFLAGS="" ./configure). Compiling +with CFLAGS="-O" also works. The gcc-2.95 compiler fixes this problem. +There may be a problem with the X server that causes programs to crash with a X_QueryColors error. If so, get a newer X server +at @url{ftp://ftp.linuxppc.org/linuxppc/contrib/linuxppc-1999/software/XFree86-FBDev-3.3.3.1-49b.ppc.rpm}. + +@end table + +Invocations (and DO) do not work well. The major problem is sending data +with data sizes less than 4 bytes (chars, shorts, etc). To fix this, we +recommend using the ffcall libraries via the @code{--enable-ffcall} +option when configuring (Read the instructions on this in the +configuration section). + +@c ----------------------------------------- +@node Irix 6.4/MIPS, MkLinux/PowerPC, GNU-Linux/PowerPC 5, Machine Specific +@section Irix 6.4/MIPS (@emph{Unstable!}) + +@table @samp +@item Recommended compiler +Unknown + +@item Extra libs needed +Unknown + +@item Special Instructions +Not ported at all to this machine. Might be better now, but no current +testing. Some files don't compile - get internal compiler +errors using gcc 2.8.1. + +@end table + +@c ----------------------------------------- +@node MkLinux/PowerPC, NetBSD, Irix 6.4/MIPS, Machine Specific +@section MkLinux/PowerPC (MkLinux DR 3) +@c Contact: Adam Fedor + +@table @samp +@item Recommended compiler +egcs-2.90.25 980302 (egcs-1.0.2 prerelease) which comes standard with +DR 3. + +@item Extra libs needed +None. + +@item Special Instructions +Comes with a good version of gcc. +Seems to compile and install ok, althouth DR3 has an old version of +glibc, which requires some workarounds which should be taken care of in +the configuration. Not completely tested, so some aspects, particular +object invocations and DO may not work properly. + +If you want threads, you'll probably have to get the latest gcc compiler +and glibc library (which has the threads library) and install both. +@end table + +@c ----------------------------------------- +@node NetBSD, Netwinder, MkLinux/PowerPC, Machine Specific +@section NetBSD +@c Contact: : David Wetzel + +@table @samp +@item Recommended compiler +Unknown + +@item Extra libs needed +Unknown + +@item Special Instructions +Can compile with shared libraries on elf architectures, although problems +persist with the NXConstantString class. Currently, to avoid this you can +redefine NXConstantString to NXConstantString2 in the libobjc library. Or +you could do the following (works on NetBSD 1.4Z) + +@example +cd /usr/lib +ar -dv libobjc_p.a NXConstStr.po +ar -dv libobjc_pic.a NXConstStr.so +ar -dv libobjc.a NXConstStr.o +rm /usr/lib/libobjc.so.0.0 +@end example + +@end table + +@c ----------------------------------------- +@node Netwinder, OpenBSD 2.x, NetBSD, Machine Specific +@section Netwinder (@emph{Unstable!}) + +@table @samp +@item Recommended compiler +Build #12 of the system. + +@item Extra libs needed +Unknown + +@item Special Instructions +See @url{http://www.netwinder.org/~patrix} +@end table + +@c ----------------------------------------- +@node OpenBSD 2.x, OSF/Alpha, Netwinder, Machine Specific +@section OpenBSD 2.x (@emph{Unstable!}) + +@table @samp +@item Recommended compiler +Unknown + +@item Extra libs needed +Unknown + +@item Special Instructions +Can only compile with static libraries. Gives a lot of warnings + +GNUstep 0.6.0 uses code to access the /proc filesystem, which may be broken +on BSD machines. To avoid this configure with the argument --enable-fake-main. +Later versions of GNUstep should check for a broken /proc filesystem. +@end table + +@c ----------------------------------------- +@node OSF/Alpha, Solaris 2.5.1/Sparc, OpenBSD 2.x, Machine Specific +@section OSF Alpha (@emph{Unstable!}) +@c Contact: suzukis@file.phys.tohoku.ac.jp + +Information is for Version 3.2C + +@table @samp +@item Recommended compiler +egcs-1.1.1/1.1.2, gcc-2.95 + +@item Extra libs needed +Unknown + +@item Special Instructions +Can only compile with static libraries. Compiler may fail when +linking executables (e.g. gdnc). Standard ranlib and ar programs are +to feable to create libraries. Should use GNU binutils versions. Linker +sometimes fails to find symbols, in which case you may need to link with +a library twice. For instance, add an extra -lgnustep-xgps in +ADDTIONAL_TOOL_LIBS in the GNUmakefile(.preamble). + +@end table + +@c ----------------------------------------- +@node Solaris 2.5.1/Sparc, Solaris 2.6/Sparc, OSF/Alpha, Machine Specific +@section Solaris 2.5.1/Sparc + +@table @samp +@item Recommended compiler +Unknown + +@item Extra libs needed +tiff, Don't use the one in /usr/openwin + +@item Special Instructions +See the Solaris 2.6 section for more instructions. +@end table + +@c ----------------------------------------- +@node Solaris 2.6/Sparc, Solaris 2.7/Intel, Solaris 2.5.1/Sparc, Machine Specific +@section Solaris 2.6/Sparc +@c Contact?: Benhur Stein + +@table @samp +@item Recommended compiler +egcs-2.91.60 (1.1.2?), egcs-1.0.1, gcc 2.8.1, gcc 2.95.2 + +@item Extra libs needed +tiff, Don't use the one in /usr/openwin + +@item Special Instructions +GCC 2.8.0 induced a problem on Solaris/Sparc +systems; however, there is a patch to fix this in the contrib directory +on the ftp sites (This is also true for all versions of gcc/egcs up +through 2.95.2 (possibly fixed in later versions)). + +To avoid using the tiff library in /usr/openwin, configure like this: +@example +LIBS=-L/usr/local/lib ./configure +@end example +if, for instance, you have put a newer tiff library in /usr/local/lib +@end table + +Even with the about patch, invocations (and DO) still don't +work well. The major problem is sending messages with more than four arguments. +We recommend using the ffcall libraries via the @code{--enable-ffcall} option +when configuring (Read the instructions on this in the configuration section). + +If you are using threads, make sure the Objective-C runtime (libobjc that comes +with gcc) is compiled with threads enabled (This is true by default) AND that +it is compiled with the _REENTRANT flag defined (This does not seem to be +true by default). + +@c ----------------------------------------- +@node Solaris 2.7/Intel, Suse 6.x/Intel, Solaris 2.6/Sparc, Machine Specific +@section Solaris 2.7/Intel +@c Contact?: Sebastian Niesen + +@table @samp +@item Recommended compiler +egcs 1.1.2 + +@item Extra libs needed +Unknown + +@item Special Instructions +Make sure there are no -g compiler flags (specify @samp{CFLAGS= +./configure}, when configuring) or remove it from @samp{OPTFLAG} +make/config.make. You will probable get a lot of text relocation +warnings, which probably can be ignored. See the other Solaris +instructions above for more information. + +@end table + +@c ----------------------------------------- +@node Suse 6.x/Intel, Suse 7.x/Intel, Solaris 2.7/Intel, Machine Specific +@section Suse 6.x/Intel +@c Contact?: colin@news.sift.co.uk + +GNUstep has been tested on version 6.2-6.4 of Suse + +@table @samp +@item Recommended compiler +Standard + +@item Extra libs needed +None + +@item Special Instructions +It seems that there is a problem with the default kernel build +distributed with Suse which means that the socket binding used by +gdnc doesn't work. If you recompile the kernel then it starts working. + +@end table + +@c ----------------------------------------- +@node Suse 7.x/Intel, Unixware-2.1.3/Intel, Suse 6.x/Intel, Machine Specific +@section Suse 7.x/Intel +@c Contact? Fred Kiefer + +GNUstep has been tested on version 7.0 of Suse + +@table @samp +@item Recommended compiler +Standard + +@item Extra libs needed +None + +@item Special Instructions +See the instructions for Suse 6.x + +@end table + +@c ----------------------------------------- +@node Unixware-2.1.3/Intel, Windows with CYGWIN, Suse 7.x/Intel, Machine Specific +@section Unixware-2.1.3/Intel +@c Contact?: Richard Frith-Macdonald + +@table @samp +@item Recommended compiler +Unknown + +@item Extra libs needed +Unknown + +@end table + +Special Instructions for GNUstep installation on Unixware 2.1 systems + +@table @asis + +@item 1 +Tune the kernel to increase the argument space so that we can pass long +command-line argument strings to processes (which the makefiles do) +(/etc/conf/bin/idtune ARG_MAX 102400) + +@item 2 +Install raft of the latest GNU software + +@format +gzip (you need this to unpack other stuff) +make (to build everything) +m4 (for autoconf etc) +autoconf (if you need to change anything) +bison +flex +binutils (required by gcc if you want to debug) +gcc-2.8.1 + (configure --with-gnu-as --with-gnu-ld --with-stabs) + NB. gcc-2.8.1 needs a fix to __do_global_dtors_aux() + in crtstuff.c on Unixware 2.1.3 + (and possibly other unixware versions) + The fix is already in recent versions of egcs. + +@end format + +@example +================================== +static void +__do_global_dtors_aux () +@{ + static func_ptr *p = __DTOR_LIST__ + 1; + static int completed = 0; + + if (completed) + return; + + while (*p) + @{ + p++; + (*(p-1)) (); + @} + +#ifdef EH_FRAME_SECTION_ASM_OP + __deregister_frame_info (__EH_FRAME_BEGIN__); +#endif + completed = 1; +@} +====================================== +@end example + +@item 3 +Having got gcc working - it's probably a good idea to rebuild +all your GNU software using it! + +@item 4 +Build gstep as normal. + +@item 5 +The SIOCGIFCONF ioctl sometimes doesn't work on unixware after applying +some of the OS patches. + +So I have added a '-a' flag to gdomap to give it the name of a file +containing IP address and netmask information for the network interfaces +on the system. + +You need to set up a file (I suggest '/etc/gdomap_addresses') containing +the information for your machine and modify your system startup files in +/etc/rc?.d to run gdomap, telling it to use that file. + +eg. If your machine has an IP address of '193.111.111.2' and is on a +class-C network, your /etc/gdomap_addresses file would contain the line + +@example +193.111.111.2 255.255.255.0 +@end example + +and your startup file would contain the lines + +@example +. /usr/local/GNUstep/Makefiles/GNUstep.sh +gdomap -a /etc/gdomap_addresses +@end example + +@end table + +If you don't set gdomap up correctly, Distributed Objects will not +work. + +@c ----------------------------------------- +@node Windows with CYGWIN, , Unixware-2.1.3/Intel, Machine Specific +@section Windows with CYGWIN (@emph{Unstable!}) +@c Contact?: Adam Fedor + +@table @samp +@item Recommended compiler +gcc 2.95.2 (Cygwin release 1.1.2 or later) + +@item Extra libs needed +Objective-C library DLL (@url{ftp://ftp.gnustep.org/pub/gnustep/contrib}) +for shared libs. + +@item Special Instructions +Static libs require no extra effort (just make shared=no), however, DLLs +(shared=yes) are compiled by default, and for this you need a special +version of the Objective-C library that also compiles as a DLL. Make sure +files and compilation done in Unix mode (no ^M in files). Due to some +interesting dependancies, it is recommended that you compile and install +each sub-package (make, base, etc) independantly. Gdomap services +not set up correctly. Must add services lines to @file{C:\WINDOWS\services} +(on Windows 98) or xxx (on Windows NT). +Base library only. No native GUI backend. +@end table + +@ifclear HOWTO +@include end.texi +@end ifclear diff --git a/Documentation/makedoc.make b/Documentation/makedoc.make new file mode 100644 index 00000000..257aa219 --- /dev/null +++ b/Documentation/makedoc.make @@ -0,0 +1,388 @@ +# -*-makefile-*- +# makedoc.make +# +# Makefile rules to build GNUstep-based texinfo documentation. +# +# Copyright (C) 1998, 2000, 2001 Free Software Foundation, Inc. +# +# Author: Scott Christley +# +# Author: Nicola Pero +# Date: November 2000 +# Changes: Support for installing documentation, and for LaTeX projects +# +# Author: Adam Fedor +# Date: Feb 2001 +# Changes: Modified to build make doc (without installation) +# +# This file is part of the GNUstep Makefile Package. +# +# This library 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. +# +# You should have received a copy of the GNU General Public +# License along with this library; see the file COPYING.LIB. +# If not, write to the Free Software Foundation, +# 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +# prevent multiple inclusions +ifeq ($(DOCUMENTATION_MAKE_LOADED),) +DOCUMENTATION_MAKE_LOADED=yes + +# +# The names of the documents are in the DOCUMENT_NAME variable. +# These final documents will be generated in info, dvi, ps, and html output. +# +# The names of text documents are in the DOCUMENT_TEXT_NAME variable. +# +# The main file for text document is in the xxx_TEXT_MAIN variable. +# The Texinfo files that needs pre-processing are in xxx_TEXI_FILES +# The GSDoc files that needs pre-processing are in xxx_GSDOC_FILES +# The LaTeX files that needs pre-processing are in xxx_LATEX_FILES +# +# Javadoc support: +# The Java classes and packages that needs documenting using javadoc +# are in xxx_JAVADOC_FILES (could contain both packages, as +# `gnu.gnustep.base', and standalone classes, as +# `gnu.gnustep.base.NSArray.java') +# +# The sourcepath to the Java classes source code in in xxx_JAVADOC_SOURCEPATH +# (it can contain more than one path, as CLASSPATH or LD_LIBRARY_PATH do). +# To set special flags for javadoc (eg, -public), use ADDITIONAL_JAVADOCFLAGS +# +# The installation directory is in the xxx_DOC_INSTALL_DIR variable +# (eg, Gui_DOC_INSTALL_DIR = Developer/Gui/Reference +# Things should be installed under `Developer/YourProjectName' or +# `User/YourProjectName' - for Javadoc, use `Developer/YourProjectName' or +# `Developer/YourProjectName/Java' if your project has both java and +# non java) +# +# Where xxx is the name of the document +# + +DOCUMENT_NAME:=$(strip $(DOCUMENT_NAME)) +DOCUMENT_TEXT_NAME:=$(strip $(DOCUMENT_TEXT_NAME)) + +ifeq ($(INTERNAL_doc_NAME)$(INTERNAL_textdoc_NAME),) +# This part is included the first time make is invoked. + +internal-all:: $(DOCUMENT_NAME:=.all.doc.variables) \ + $(DOCUMENT_TEXT_NAME:=.all.textdoc.variables) + +internal-install:: all $(DOCUMENT_NAME:=.install.doc.variables) \ + $(DOCUMENT_TEXT_NAME:=.install.textdoc.variables) + +internal-uninstall:: $(DOCUMENT_NAME:=.uninstall.doc.variables) \ + $(DOCUMENT_TEXT_NAME:=.uninstall.textdoc.variables) + +internal-clean:: $(DOCUMENT_NAME:=.clean.doc.variables) \ + $(DOCUMENT_TEXT_NAME:=.clean.textdoc.variables) + +internal-distclean:: $(DOCUMENT_NAME:=.distclean.doc.variables) \ + $(DOCUMENT_TEXT_NAME:=.distclean.textdoc.variables) + +#$(DOCUMENT_NAME): +# @$(MAKE) -f $(MAKEFILE_NAME) --no-print-directory \ +# $@.all.doc.variables + +else +# This part gets included the second time make is invoked. + +# +# Internal targets +# + +# +# Compilation targets +# + +# +# Compilation of texinfo files +# +ifneq ($(TEXI_FILES),) + +internal-doc-all:: before-all before-$(TARGET)-all \ + $(INTERNAL_doc_NAME).info \ + $(INTERNAL_doc_NAME).ps \ + $(INTERNAL_doc_NAME)_toc.html \ + after-$(TARGET)-all after-all + +internal-textdoc-all:: before-all before-$(TARGET)-all \ + $(INTERNAL_textdoc_NAME) \ + after-$(TARGET)-all after-all + +$(INTERNAL_doc_NAME).info: $(TEXI_FILES) + $(GNUSTEP_MAKEINFO) $(GNUSTEP_MAKEINFO_FLAGS) \ + -o $@ $(INTERNAL_doc_NAME).texi + +$(INTERNAL_doc_NAME).dvi: $(TEXI_FILES) + $(GNUSTEP_TEXI2DVI) $(GNUSTEP_TEXI2DVI_FLAGS) $(INTERNAL_doc_NAME).texi + +$(INTERNAL_doc_NAME).ps: $(INTERNAL_doc_NAME).dvi + $(GNUSTEP_DVIPS) $(GNUSTEP_DVIPS_FLAGS) \ + $(INTERNAL_doc_NAME).dvi -o $@ + +$(INTERNAL_doc_NAME)_toc.html: $(TEXI_FILES) + $(GNUSTEP_TEXI2HTML) $(GNUSTEP_TEXI2HTML_FLAGS) \ + $(INTERNAL_doc_NAME).texi + +$(INTERNAL_textdoc_NAME): $(TEXI_FILES) $(TEXT_MAIN) + $(GNUSTEP_MAKETEXT) $(GNUSTEP_MAKETEXT_FLAGS) \ + -o $@ $(TEXT_MAIN) + +endif # TEXI_FILES + +before-$(TARGET)-all:: + +after-$(TARGET)-all:: + + +# +# Compilation of gsdoc files +# +ifneq ($(GSDOC_FILES),) + +internal-doc-all:: before-all before-$(TARGET)-all \ + $(INTERNAL_doc_NAME).html \ + after-$(TARGET)-all after-all + +$(INTERNAL_doc_NAME).html: $(GSDOC_FILES) + gsdoc $(GSDOC_FILES) + +endif # GSDOC_FILES + +# +# Compilation of LaTeX files +# +ifneq ($(LATEX_FILES),) +# +# Targets which are always built +# +$(INTERNAL_doc_NAME).dvi: $(LATEX_FILES) + latex $(INTERNAL_doc_NAME).tex + latex $(INTERNAL_doc_NAME).tex + +$(INTERNAL_doc_NAME).ps: $(INTERNAL_doc_NAME).dvi + $(GNUSTEP_DVIPS) $(GNUSTEP_DVIPS_FLAGS) \ + $(INTERNAL_doc_NAME).dvi -o $@ + +$(INTERNAL_doc_NAME).ps.gz: $(INTERNAL_doc_NAME).ps + gzip $(INTERNAL_doc_NAME).ps -c > $(INTERNAL_doc_NAME).ps.gz + +internal-doc-all:: before-all before-$(TARGET)-all \ + $(INTERNAL_doc_NAME).ps.gz + +# +# Targets built only if we can find `latex2html' +# +# NB: you may set LATEX2HTML on the command line if the following doesn't work +LATEX2HTML = $(shell which latex2html) + +ifneq ($(LATEX2HTML),) +internal-doc-all:: $(INTERNAL_doc_NAME).tar.gz + +$(INTERNAL_doc_NAME)/$(INTERNAL_doc_NAME).html: $(INTERNAL_doc_NAME).dvi + $(LATEX2HTML) $(INTERNAL_doc_NAME) + +$(INTERNAL_doc_NAME).tar.gz: $(INTERNAL_doc_NAME)/$(INTERNAL_doc_NAME).html + $(TAR) cf $(INTERNAL_doc_NAME).tar.gz $(INTERNAL_doc_NAME) + +endif # LATEX2HTML + +internal-doc-all:: after-$(TARGET)-all after-all + +endif # LATEX_FILES + +# +# Documentation generated with javadoc +# +ifneq ($(JAVADOC_FILES),) + +internal-doc-all:: before-$(TARGET)-all \ + $(INTERNAL_doc_NAME)/index.html \ + after-$(TARGET)-all + +ifeq ($(JAVADOC_SOURCEPATH),) + INTERNAL_JAVADOCFLAGS = -sourcepath ./ +else + INTERNAL_JAVADOCFLAGS = -sourcepath ./:$(strip $(JAVADOC_SOURCEPATH)) +endif + +$(INTERNAL_doc_NAME)/index.html: + $(MKDIRS) $(INTERNAL_doc_NAME); \ + $(JAVADOC) $(ALL_JAVADOCFLAGS) $(JAVADOC_FILES) -d $(INTERNAL_doc_NAME) + +endif # GSDOC_FILES + +# +# Install and uninstall targets +# + +# +# Installation directory - always created +# +internal-doc-install:: internal-install-dirs + +internal-install-dirs:: + $(MKDIRS) $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) + +# +# texi installation +# +ifneq ($(TEXI_FILES),) +internal-doc-install:: + $(INSTALL_DATA) $(INTERNAL_doc_NAME).ps \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) + $(INSTALL_DATA) $(INTERNAL_doc_NAME).info \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) + $(INSTALL_DATA) $(INTERNAL_doc_NAME)_*.html \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) +internal-doc-uninstall:: + rm -f \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/$(INTERNAL_doc_NAME).ps + rm -f \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/$(INTERNAL_doc_NAME).info + rm -f \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/$(INTERNAL_doc_NAME)_*.html +endif # TEXI_FILES + +# +# gsdoc installation +# +ifneq ($(GSDOC_FILES),) + +GSDOC_OBJECT_FILES = $(patsubst %.gsdoc,%.html,$(GSDOC_FILES)) + +internal-doc-install:: + $(INSTALL_DATA) $(GSDOC_OBJECT_FILES) \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) +internal-doc-uninstall:: + rm -f \ + $(addprefix $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/,\ + $(GSDOC_OBJECT_FILES)) +endif # GSDOC_FILES + +# +# LaTeX installation +# +ifneq ($(LATEX_FILES),) +internal-doc-install:: + $(INSTALL_DATA) $(INTERNAL_doc_NAME).ps \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) +internal-doc-uninstall:: + rm -f \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/$(INTERNAL_doc_NAME).ps + +ifneq ($(LATEX2HTML),) +internal-doc-install:: + $(INSTALL_DATA) $(INTERNAL_doc_NAME)/*.html \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) + $(INSTALL_DATA) $(INTERNAL_doc_NAME)/*.css \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) +# Yeah - I know - the following is dangerous if you have misused the +# DOC_INSTALL_DIR - but it's the only way to do it +internal-doc-uninstall:: + -rm -f $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/*.html + -rm -f $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/*.css +endif # LATEX2HTML +endif # LATEX_FILES + +# +# Javadoc installation +# +ifneq ($(JAVADOC_FILES),) + +internal-doc-install:: + rm -rf $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/$(INTERNAL_doc_NAME) + $(TAR) cf - $(INTERNAL_doc_NAME) | \ + (cd $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR); $(TAR) xf -) + +internal-doc-uninstall:: + -rm -f $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/$(INTERNAL_doc_NAME) + +endif # JAVADOC_FILES + +# +# text file installation +# +internal-textdoc-install:: internal-install-dirs + $(INSTALL_DATA) $(INTERNAL_textdoc_NAME) \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR) + +internal-textdoc-uninstall:: + rm -f \ + $(GNUSTEP_DOCUMENTATION)/$(DOC_INSTALL_DIR)/$(INTERNAL_textdoc_NAME) + +# +# Cleaning targets +# +internal-doc-clean:: + rm -f $(INTERNAL_doc_NAME).aux + rm -f $(INTERNAL_doc_NAME).cp + rm -f $(INTERNAL_doc_NAME).cps + rm -f $(INTERNAL_doc_NAME).dvi + rm -f $(INTERNAL_doc_NAME).fn + rm -f $(INTERNAL_doc_NAME).info + rm -f $(INTERNAL_doc_NAME).ky + rm -f $(INTERNAL_doc_NAME).log + rm -f $(INTERNAL_doc_NAME).pg + rm -f $(INTERNAL_doc_NAME).ps + rm -f $(INTERNAL_doc_NAME).toc + rm -f $(INTERNAL_doc_NAME).tp + rm -f $(INTERNAL_doc_NAME).vr + rm -f $(INTERNAL_doc_NAME).vrs + rm -f $(INTERNAL_doc_NAME)_*.html + rm -f $(INTERNAL_doc_NAME).ps.gz + rm -f $(INTERNAL_doc_NAME).tar.gz + -rm -f $(INTERNAL_doc_NAME)/* +ifneq ($(GSDOC_FILES),) + for i in $(GSDOC_FILES); do \ + rm -f `basename $$i .gsdoc`.html ; \ + done +endif +ifneq ($(LATEX_FILES),) + for i in $(LATEX_FILES); do \ + rm -f `basename $$i .tex`.aux ; \ + done +endif + +internal-textdoc-clean:: + rm -f $(INTERNAL_textdoc_NAME) +ifneq ($(GSDOC_FILES),) + for i in $(GSDOC_FILES); do \ + rm -f `basename $$i .gsdoc`.html ; \ + done +endif + +ifneq ($(JAVADOC_FILES),) + +internal-doc-distclean:: + rm -Rf $(INTERNAL_doc_NAME) + +endif # JAVADOC_FILES + +ifneq ($(LATEX_FILES),) + +internal-doc-distclean:: + rm -Rf *~ + rm -Rf *.aux +else # ! LATEX_FILES +internal-doc-distclean:: + rm -Rf *~ +endif # LATEX_FILES + +internal-textdoc-distclean:: + +# +# Testing targets +# +internal-doc-check:: + +internal-textdoc-check:: + +endif + +endif +# documentation.make loaded diff --git a/Documentation/makerules.make b/Documentation/makerules.make new file mode 100644 index 00000000..6bae9a84 --- /dev/null +++ b/Documentation/makerules.make @@ -0,0 +1,455 @@ +# +# rules.make +# +# All of the common makefile rules. +# +# Copyright (C) 1997 Free Software Foundation, Inc. +# +# Author: Scott Christley +# Author: Ovidiu Predescu +# +# This file is part of the GNUstep Makefile Package. +# +# This library 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. +# +# You should have received a copy of the GNU General Public +# License along with this library; see the file COPYING.LIB. +# If not, write to the Free Software Foundation, +# 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. + +# prevent multiple inclusions +ifeq ($(RULES_MAKE_LOADED),) +RULES_MAKE_LOADED=yes + +# This part is included the first time make is invoked. This part defines the +# global targets and the following implicit rule which determines the +# TARGET_TYPE of the next thing to be build in the following make invocation +# (a library, application, tool etc.), the current name of the target from a +# specific library/application/tool/etc list and the OPERATION to be performed +# (all, install, clean, distclean etc.). + +# This target has to be called with the name of the actual target, followed +# by the operation, then the makefile fragment to be called and then the +# variables word. Suppose for example we build the library libgmodel, the +# target should look like: +# +# libgmodel.all.library.variables +# +%.variables: + @(target=`echo $* | sed -e 's/\(.*\)\.\(.*\)\.\(.*\)/\1/'`; \ + operation=`echo $* | sed -e 's/\(.*\)\.\(.*\)\.\(.*\)/\2/'`; \ + type=`echo $* | sed -e 's/\(.*\)\.\(.*\)\.\(.*\)/\3/' | tr - _`; \ + $(MAKE) -f $(MAKEFILE_NAME) --no-print-directory --no-keep-going \ + TARGET_TYPE=$${type} \ + OPERATION=$${operation} TARGET=$${target} \ + PROCESS_SECOND_TIME=yes $${target}.build \ + OBJCFLAGS="$(OBJCFLAGS)" CFLAGS="$(CFLAGS)" \ + OPTFLAG="$(OPTFLAG)" ) + +# +# Global targets +# +all:: before-all internal-all after-all + +install:: before-install internal-install after-install + +uninstall:: before-uninstall internal-uninstall after-uninstall + +clean:: before-clean internal-clean after-clean + +ifeq ($(MAKELEVEL),0) +distclean:: clean before-distclean internal-distclean after-distclean +else +distclean:: before-distclean internal-distclean after-distclean +endif + +check:: before-check internal-check after-check + +# +# Placeholders for internal targets +# + +before-all:: + +internal-all:: + +after-all:: + +before-install:: + +internal-install:: + +after-install:: + +before-uninstall:: + +internal-uninstall:: + +after-uninstall:: + +before-clean:: + +internal-clean:: + rm -rf *~ + +after-clean:: + +before-distclean:: + +internal-distclean:: + +after-distclean:: + +before-check:: + +internal-check:: + +after-check:: + +# declare targets as PHONY + +.PHONY = all before-all internal-all after-all \ + install before-install internal-install after-install \ + uninstall before-uninstall internal-uninstall after-uninstall \ + clean before-clean internal-clean after-clean \ + distclean before-distclean internal-distclean after-distclean \ + check before-check internal-check after-check + +ifeq ($(PROCESS_SECOND_TIME),yes) + +ALL_CPPFLAGS = $(CPPFLAGS) $(ADDITIONAL_CPPFLAGS) $(AUXILIARY_CPPFLAGS) + +ALL_OBJCFLAGS = $(INTERNAL_OBJCFLAGS) $(ADDITIONAL_OBJCFLAGS) \ + $(AUXILIARY_OBJCFLAGS) $(ADDITIONAL_INCLUDE_DIRS) \ + $(AUXILIARY_INCLUDE_DIRS) -I. $(SYSTEM_INCLUDES) \ + $(GNUSTEP_USER_FRAMEWORKS_HEADERS_FLAG) \ + $(GNUSTEP_LOCAL_FRAMEWORKS_HEADERS_FLAG) \ + $(GNUSTEP_NETWORK_FRAMEWORKS_HEADERS_FLAG) \ + -I$(GNUSTEP_SYSTEM_FRAMEWORKS_HEADERS) \ + $(GNUSTEP_HEADERS_FND_FLAG) $(GNUSTEP_HEADERS_GUI_FLAG) \ + $(GNUSTEP_HEADERS_TARGET_FLAG) $(GNUSTEP_USER_HEADERS_FLAG) \ + $(GNUSTEP_LOCAL_HEADERS_FLAG) $(GNUSTEP_NETWORK_HEADERS_FLAG) \ + -I$(GNUSTEP_SYSTEM_HEADERS) + +ALL_CFLAGS = $(INTERNAL_CFLAGS) $(ADDITIONAL_CFLAGS) \ + $(AUXILIARY_CFLAGS) $(ADDITIONAL_INCLUDE_DIRS) \ + $(AUXILIARY_INCLUDE_DIRS) -I. $(SYSTEM_INCLUDES) \ + $(GNUSTEP_USER_FRAMEWORKS_HEADERS_FLAG) \ + $(GNUSTEP_LOCAL_FRAMEWORKS_HEADERS_FLAG) \ + $(GNUSTEP_NETWORK_FRAMEWORKS_HEADERS_FLAG) \ + -I$(GNUSTEP_SYSTEM_FRAMEWORKS_HEADERS) \ + $(GNUSTEP_HEADERS_FND_FLAG) $(GNUSTEP_HEADERS_GUI_FLAG) \ + $(GNUSTEP_HEADERS_TARGET_FLAG) $(GNUSTEP_USER_HEADERS_FLAG) \ + $(GNUSTEP_LOCAL_HEADERS_FLAG) $(GNUSTEP_NETWORK_HEADERS_FLAG) \ + -I$(GNUSTEP_SYSTEM_HEADERS) + +ALL_JAVACFLAGS = $(INTERNAL_JAVACFLAGS) $(ADDITIONAL_JAVACFLAGS) \ + $(AUXILIARY_JAVACFLAGS) + +ALL_JAVAHFLAGS = $(INTERNAL_JAVAHFLAGS) $(ADDITIONAL_JAVAHFLAGS) \ + $(AUXILIARY_JAVAHFLAGS) + +ALL_JAVADOCFLAGS = $(INTERNAL_JAVADOCFLAGS) $(ADDITIONAL_JAVADOCFLAGS) \ + $(AUXILIARY_JAVADOCFLAGS) + +ALL_LDFLAGS = $(ADDITIONAL_LDFLAGS) $(AUXILIARY_LDFLAGS) $(GUI_LDFLAGS) \ + $(BACKEND_LDFLAGS) $(SYSTEM_LDFLAGS) $(INTERNAL_LDFLAGS) + +# +# The bundle extension (default is .bundle) is defined by BUNDLE_EXTENSION. +# +ifeq ($(strip $(BUNDLE_EXTENSION)),) +BUNDLE_EXTENSION = .bundle +endif + + +# General rules +VPATH = . + +.SUFFIXES: .m .c .psw .java .h + +.PRECIOUS: %.c %.h $(GNUSTEP_OBJ_DIR)/%${OEXT} + +$(GNUSTEP_OBJ_DIR)/%${OEXT} : %.c + $(CC) $< -c $(ALL_CPPFLAGS) $(ALL_CFLAGS) -o $@ + +$(GNUSTEP_OBJ_DIR)/%${OEXT} : %.m + $(CC) $< -c $(ALL_CPPFLAGS) $(ALL_OBJCFLAGS) -o $@ + +%.class : %.java + $(JAVAC) $(ALL_JAVACFLAGS) $< + +# A jni header file which is created using JAVAH +# Example of how this rule will be applied: +# gnu/gnustep/base/NSObject.h : gnu/gnustep/base/NSObject.java +# javah -o gnu/gnustep/base/NSObject.h gnu.gnustep.base.NSObject +%.h : %.java + $(JAVAH) $(ALL_JAVAHFLAGS) -o $@ $(subst /,.,$*) + +%.c : %.psw + pswrap -h $*.h -o $@ $< + +# The magical application rules, thank you GNU make! +%.build: + @(if [ "$(FRAMEWORK_NAME)" != "" ] && [ "$(OPERATION)" = "all" ] && [ "$(TOOL_NAME)" = "" ]; then \ + echo Build public headers for $(TARGET_TYPE) $*...; \ + $(MAKE) -f $(MAKEFILE_NAME) --no-print-directory --no-keep-going \ + build-framework-headers \ + INTERNAL_$(TARGET_TYPE)_NAME=$* \ + SUBPROJECTS="$($*_SUBPROJECTS)" \ + TOOLS="$($*_TOOLS)" \ + OBJC_FILES="$($*_OBJC_FILES)" \ + C_FILES="$($*_C_FILES)" \ + JAVA_FILES="$($*_JAVA_FILES)" \ + JAVA_JNI_FILES="$($*_JAVA_JNI_FILES)" \ + OBJ_FILES="$($*_OBJ_FILES)" \ + PSWRAP_FILES="$($*_PSWRAP_FILES)" \ + HEADER_FILES="$($*_HEADER_FILES)" \ + TEXI_FILES="$($*_TEXI_FILES)" \ + GSDOC_FILES="$($*_GSDOC_FILES)" \ + LATEX_FILES="$($*_LATEX_FILES)" \ + JAVADOC_FILES="$($*_JAVADOC_FILES)" \ + JAVADOC_SOURCEPATH="$($*_JAVADOC_SOURCEPATH)" \ + DOC_INSTALL_DIR="$($*_DOC_INSTALL_DIR)" \ + TEXT_MAIN="$($*_TEXT_MAIN)" \ + HEADER_FILES_DIR="$($*_HEADER_FILES_DIR)" \ + HEADER_FILES_INSTALL_DIR="$($*_HEADER_FILES_INSTALL_DIR)" \ + COMPONENTS="$($*_COMPONENTS)" \ + LANGUAGES="$($*_LANGUAGES)" \ + HAS_GSWCOMPONENTS="$($*_HAS_GSWCOMPONENTS)" \ + GSWAPP_INFO_PLIST="$($*_GSWAPP_INFO_PLIST)" \ + WEBSERVER_RESOURCE_FILES="$($*_WEBSERVER_RESOURCE_FILES)" \ + LOCALIZED_WEBSERVER_RESOURCE_FILES="$($*_LOCALIZED_WEBSERVER_RESOURCE_FILES)" \ + WEBSERVER_RESOURCE_DIRS="$($*_WEBSERVER_RESOURCE_DIRS)" \ + LOCALIZED_RESOURCE_FILES="$($*_LOCALIZED_RESOURCE_FILES)" \ + RESOURCE_FILES="$($*_RESOURCE_FILES)" \ + MAIN_MODEL_FILE="$($*_MAIN_MODEL_FILE)" \ + RESOURCE_DIRS="$($*_RESOURCE_DIRS)" \ + BUNDLE_LIBS="$($*_BUNDLE_LIBS) $(BUNDLE_LIBS)" \ + SERVICE_INSTALL_DIR="$($*_SERVICE_INSTALL_DIR)" \ + APPLICATION_ICON="$($*_APPLICATION_ICON)" \ + PALETTE_ICON="$($*_PALETTE_ICON)" \ + PRINCIPAL_CLASS="$($*_PRINCIPAL_CLASS)" \ + DLL_DEF="$($*_DLL_DEF)" \ + ADDITIONAL_INCLUDE_DIRS="$(ADDITIONAL_INCLUDE_DIRS) \ + $($*_INCLUDE_DIRS)" \ + ADDITIONAL_GUI_LIBS="$($*_GUI_LIBS) $(ADDITIONAL_GUI_LIBS)" \ + ADDITIONAL_TOOL_LIBS="$($*_TOOL_LIBS) $(ADDITIONAL_TOOL_LIBS)" \ + ADDITIONAL_OBJC_LIBS="$($*_OBJC_LIBS) $(ADDITIONAL_OBJC_LIBS)" \ + ADDITIONAL_LIBRARY_LIBS="$($*_LIBS) $($*_LIBRARY_LIBS) $(ADDITIONAL_LIBRARY_LIBS)" \ + ADDITIONAL_LIB_DIRS="$($*_LIB_DIRS) $(ADDITIONAL_LIB_DIRS)" \ + ADDITIONAL_LDFLAGS="$($*_LDFLAGS) $(ADDITIONAL_LDFLAGS)" \ + LIBRARIES_DEPEND_UPON="$(shell $(WHICH_LIB_SCRIPT) \ + $(LIB_DIRS_NO_SYSTEM) $($*_LIB_DIRS) $(ADDITIONAL_LIB_DIRS) \ + $(LIBRARIES_DEPEND_UPON) \ + $($*_LIBRARIES_DEPEND_UPON) debug=$(debug) profile=$(profile) \ + shared=$(shared) libext=$(LIBEXT) \ + shared_libext=$(SHARED_LIBEXT))" \ + SCRIPTS_DIRECTORY="$($*_SCRIPTS_DIRECTORY)" \ + CHECK_SCRIPT_DIRS="$($*_SCRIPT_DIRS)"; \ + if [ "$($*_SUBPROJECTS)" != "" ]; then subprjs="$($*_SUBPROJECTS)"; \ + else subprjs="__dummy__";\ + fi;\ + fi;) + @(echo Making $(OPERATION) for $(TARGET_TYPE) $*...; \ + if [ "$(FRAMEWORK_NAME)" != "" ] && [ "$($*_TOOLS)" != "" ] && [ "$(OPERATION)" != "build-framework-headers" ]; then tools="$($*_TOOLS)"; \ + else tools="__dummy__";\ + fi;\ + if [ "$$tools" != "__dummy__" ]; then \ + for f in $$tools; do \ + mf=$(MAKEFILE_NAME); \ + if [ ! -f $$f/$$mf -a -f $$f/Makefile ]; then \ + mf=Makefile; \ + echo "WARNING: No $(MAKEFILE_NAME) found for tool $ff; using 'Makefile'"; \ + fi; \ + if $(MAKE) -C $$f -f $$mf --no-keep-going $(OPERATION) \ + FRAMEWORK_NAME="$(FRAMEWORK_NAME)" \ + FRAMEWORK_VERSION_DIR_NAME="../$(FRAMEWORK_VERSION_DIR_NAME)" \ + FRAMEWORK_OPERATION="$(OPERATION)" \ + TOOL_OPERATION="$(OPERATION)" \ + DERIVED_SOURCES="../$(DERIVED_SOURCES)" \ + SUBPROJECT_ROOT_DIR="$(SUBPROJECT_ROOT_DIR)/$$f" \ + ; then \ + :; \ + else exit $$?; \ + fi; \ + done; \ + fi; \ + if [ "$($*_SUBPROJECTS)" != "" ]; then subprjs="$($*_SUBPROJECTS)"; \ + else subprjs="__dummy__";\ + fi;\ + if [ "$$subprjs" != "__dummy__" ]; then \ + for f in $$subprjs; do \ + mf=$(MAKEFILE_NAME); \ + if [ ! -f $$f/$$mf -a -f $$f/Makefile ]; then \ + mf=Makefile; \ + echo "WARNING: No $(MAKEFILE_NAME) found for subproject $ff; using 'Makefile'"; \ + fi; \ + if $(MAKE) -C $$f -f $$mf --no-keep-going $(OPERATION) \ + FRAMEWORK_NAME="$(FRAMEWORK_NAME)" \ + FRAMEWORK_VERSION_DIR_NAME="../$(FRAMEWORK_VERSION_DIR_NAME)" \ + DERIVED_SOURCES="../$(DERIVED_SOURCES)" \ + SUBPROJECT_ROOT_DIR="$(SUBPROJECT_ROOT_DIR)/$$f" \ + ; then \ + :; \ + else exit $$?; \ + fi; \ + done; \ + fi; \ + $(MAKE) -f $(MAKEFILE_NAME) --no-print-directory --no-keep-going \ + internal-$(TARGET_TYPE)-$(OPERATION) \ + INTERNAL_$(TARGET_TYPE)_NAME=$* \ + SUBPROJECTS="$($*_SUBPROJECTS)" \ + OBJC_FILES="$($*_OBJC_FILES)" \ + C_FILES="$($*_C_FILES)" \ + JAVA_FILES="$($*_JAVA_FILES)" \ + JAVA_JNI_FILES="$($*_JAVA_JNI_FILES)" \ + OBJ_FILES="$($*_OBJ_FILES)" \ + PSWRAP_FILES="$($*_PSWRAP_FILES)" \ + HEADER_FILES="$($*_HEADER_FILES)" \ + TEXI_FILES="$($*_TEXI_FILES)" \ + GSDOC_FILES="$($*_GSDOC_FILES)" \ + LATEX_FILES="$($*_LATEX_FILES)" \ + JAVADOC_FILES="$($*_JAVADOC_FILES)" \ + JAVADOC_SOURCEPATH="$($*_JAVADOC_SOURCEPATH)" \ + DOC_INSTALL_DIR="$($*_DOC_INSTALL_DIR)" \ + TEXT_MAIN="$($*_TEXT_MAIN)" \ + HEADER_FILES_DIR="$($*_HEADER_FILES_DIR)" \ + HEADER_FILES_INSTALL_DIR="$($*_HEADER_FILES_INSTALL_DIR)" \ + COMPONENTS="$($*_COMPONENTS)" \ + LANGUAGES="$($*_LANGUAGES)" \ + HAS_GSWCOMPONENTS="$($*_HAS_GSWCOMPONENTS)" \ + GSWAPP_INFO_PLIST="$($*_GSWAPP_INFO_PLIST)" \ + WEBSERVER_RESOURCE_FILES="$($*_WEBSERVER_RESOURCE_FILES)" \ + LOCALIZED_WEBSERVER_RESOURCE_FILES="$($*_LOCALIZED_WEBSERVER_RESOURCE_FILES)" \ + WEBSERVER_RESOURCE_DIRS="$($*_WEBSERVER_RESOURCE_DIRS)" \ + LOCALIZED_RESOURCE_FILES="$($*_LOCALIZED_RESOURCE_FILES)" \ + RESOURCE_FILES="$($*_RESOURCE_FILES)" \ + MAIN_MODEL_FILE="$($*_MAIN_MODEL_FILE)" \ + RESOURCE_DIRS="$($*_RESOURCE_DIRS)" \ + BUNDLE_LIBS="$($*_BUNDLE_LIBS) $(BUNDLE_LIBS)" \ + SERVICE_INSTALL_DIR="$($*_SERVICE_INSTALL_DIR)" \ + APPLICATION_ICON="$($*_APPLICATION_ICON)" \ + PALETTE_ICON="$($*_PALETTE_ICON)" \ + PRINCIPAL_CLASS="$($*_PRINCIPAL_CLASS)" \ + DLL_DEF="$($*_DLL_DEF)" \ + ADDITIONAL_INCLUDE_DIRS="$(ADDITIONAL_INCLUDE_DIRS) \ + $($*_INCLUDE_DIRS)" \ + ADDITIONAL_GUI_LIBS="$($*_GUI_LIBS) $(ADDITIONAL_GUI_LIBS)" \ + ADDITIONAL_TOOL_LIBS="$($*_TOOL_LIBS) $(ADDITIONAL_TOOL_LIBS)" \ + ADDITIONAL_OBJC_LIBS="$($*_OBJC_LIBS) $(ADDITIONAL_OBJC_LIBS)" \ + ADDITIONAL_LIBRARY_LIBS="$($*_LIBS) $($*_LIBRARY_LIBS) $(ADDITIONAL_LIBRARY_LIBS)" \ + ADDITIONAL_LIB_DIRS="$($*_LIB_DIRS) $(ADDITIONAL_LIB_DIRS)" \ + ADDITIONAL_LDFLAGS="$($*_LDFLAGS) $(ADDITIONAL_LDFLAGS)" \ + LIBRARIES_DEPEND_UPON="$(shell $(WHICH_LIB_SCRIPT) \ + $(LIB_DIRS_NO_SYSTEM) $($*_LIB_DIRS) $(ADDITIONAL_LIB_DIRS) \ + $(LIBRARIES_DEPEND_UPON) \ + $($*_LIBRARIES_DEPEND_UPON) debug=$(debug) profile=$(profile) \ + shared=$(shared) libext=$(LIBEXT) \ + shared_libext=$(SHARED_LIBEXT))" \ + SCRIPTS_DIRECTORY="$($*_SCRIPTS_DIRECTORY)" \ + CHECK_SCRIPT_DIRS="$($*_SCRIPT_DIRS)" \ + ) + +# +# The list of Objective-C source files to be compiled +# are in the OBJC_FILES variable. +# +# The list of C source files to be compiled +# are in the C_FILES variable. +# +# The list of PSWRAP source files to be compiled +# are in the PSWRAP_FILES variable. +# +# The list of JAVA source files to be compiled +# are in the JAVA_FILES variable. +# +# The list of JAVA source files from which to generate jni headers +# are in the JAVA_JNI_FILES variable. +# + + +ifneq ($($*_SUBPROJECTS),) + SUBPROJECT_OBJ_FILES = $(foreach d, $($*_SUBPROJECTS), \ + $(addprefix $(d)/, $(GNUSTEP_OBJ_DIR)/$(SUBPROJECT_PRODUCT))) +else + ifneq ($(SUBPROJECTS),) + SUBPROJECT_OBJ_FILES = $(foreach d, $(SUBPROJECTS), \ + $(addprefix $(d)/, $(GNUSTEP_OBJ_DIR)/$(SUBPROJECT_PRODUCT))) + endif +endif + +#ifneq ($(SUBPROJECTS),) +# SUBPROJECT_OBJ_FILES = $(foreach d, $(SUBPROJECTS), \ +# $(addprefix $(d)/, $(GNUSTEP_OBJ_DIR)/$(SUBPROJECT_PRODUCT))) +#endif + +OBJC_OBJS = $(OBJC_FILES:.m=${OEXT}) +OBJC_OBJ_FILES = $(addprefix $(GNUSTEP_OBJ_DIR)/,$(OBJC_OBJS)) + +JAVA_OBJS = $(JAVA_FILES:.java=.class) +JAVA_OBJ_FILES = $(JAVA_OBJS) + +JAVA_JNI_OBJS = $(JAVA_JNI_FILES:.java=.h) +JAVA_JNI_OBJ_FILES = $(JAVA_JNI_OBJS) + +PSWRAP_C_FILES = $(PSWRAP_FILES:.psw=.c) +PSWRAP_H_FILES = $(PSWRAP_FILES:.psw=.h) +PSWRAP_OBJS = $(PSWRAP_FILES:.psw=${OEXT}) +PSWRAP_OBJ_FILES = $(addprefix $(GNUSTEP_OBJ_DIR)/,$(PSWRAP_OBJS)) + +C_OBJS = $(C_FILES:.c=${OEXT}) +C_OBJ_FILES = $(PSWRAP_OBJ_FILES) $(addprefix $(GNUSTEP_OBJ_DIR)/,$(C_OBJS)) + +ifeq ($(WITH_DLL),yes) +TMP_LIBS := $(LIBRARIES_DEPEND_UPON) $(BUNDLE_LIBS) $(ADDITIONAL_GUI_LIBS) $(ADDITIONAL_OBJC_LIBS) $(ADDITIONAL_LIBRARY_LIBS) +TMP_LIBS := $(filter -l%, $(TMP_LIBS)) +# filter all non-static libs (static libs are those ending in _ds, _s, _ps..) +TMP_LIBS := $(filter-out -l%_ds, $(TMP_LIBS)) +TMP_LIBS := $(filter-out -l%_s, $(TMP_LIBS)) +TMP_LIBS := $(filter-out -l%_dps,$(TMP_LIBS)) +TMP_LIBS := $(filter-out -l%_ps, $(TMP_LIBS)) +# strip away -l, _p and _d .. +TMP_LIBS := $(TMP_LIBS:-l%=%) +TMP_LIBS := $(TMP_LIBS:%_d=%) +TMP_LIBS := $(TMP_LIBS:%_p=%) +TMP_LIBS := $(TMP_LIBS:%_dp=%) +TMP_LIBS := $(shell echo $(TMP_LIBS)|tr '-' '_') +ALL_CPPFLAGS += $(TMP_LIBS:%=-Dlib%_ISDLL=1) +endif + +# Rules processed second time +endif + +# +# Common variables for frameworks +# +ifeq ($(CURRENT_VERSION_NAME),) + CURRENT_VERSION_NAME := A +endif +ifeq ($(DEPLOY_WITH_CURRENT_VERSION),) + DEPLOY_WITH_CURRENT_VERSION := yes +endif + +FRAMEWORK_NAME := $(strip $(FRAMEWORK_NAME)) +FRAMEWORK_DIR_NAME := $(FRAMEWORK_NAME:=.framework) +FRAMEWORK_VERSION_DIR_NAME := $(FRAMEWORK_DIR_NAME)/Versions/$(CURRENT_VERSION_NAME) +SUBPROJECT_ROOT_DIR := "." + +ifeq ($(OBJ_DIR_RULE),) +OBJ_DIR_RULE = defined +# The rule to create the objects file directory. This rule is here so that it +# can be accessed from the global before and after targets as well. +$(GNUSTEP_OBJ_DIR): + @$(MKDIRS) ./$(GNUSTEP_OBJ_DIR) +endif + +endif +# rules.make loaded + +## Local variables: +## mode: makefile +## End: diff --git a/FAQ b/FAQ new file mode 100644 index 00000000..22966a28 --- /dev/null +++ b/FAQ @@ -0,0 +1,740 @@ +\input texinfo + +GNUstep Frequently Asked Questions with Answers +*********************************************** + + Last updated 26 February 2001 Please send corrections to +. + +GNUstep General Information +=========================== + +What is GNUstep? +---------------- + + GNUstep is the Free Software Foundation's effort to implement NeXT +Software Inc.'s (now Apple Inc.) OpenStep Standard. The project is not +finished, however some components are useable now. + + The GNUstep project consists of the following sub-projects: + + * GNU Objective C Compiler and Objective C Runtime Library - + Although not actually a component of GNUstep, GCC and the GNU + Objective C Runtime Library are integral to GNUstep, since they + are used to make every GNU Objective C program. + + * GNUstep Base Library - Code for non-graphical objects, such as + strings, collections, archiving support and distributed objects + messaging. (Including functionality similar to OpenStep's + `FoundationKit'.) + + * GNUstep GUI Library - Code for graphical objects used in making a + Graphical User Interface (GUI). This includes buttons, sliders, + text fields, windows, menus, etc. (Including functionality + similar to OpenStep's `AppKit'.) + + * GNUstep DisplayGhostscript Server - A server that draws PostScript + graphics to the screen, and receives events from the keyboard and + mouse. It is based on GhostScript. There is also an DPS extension + to Xfree*6 that is usable. + + * Various Tools and applications, including GORM, The GNUstep + interface builder for graphically assembling application + interfaces, and ProjectCenter, a project manager. + + +What is the OpenStep standard? +------------------------------ + + OpenStep is an Application Programming Interface (API) for creating +applications using the Objective C language. It was published by NeXT +Computer Inc. in 1994. + + OpenStep consists of three parts: the `FoundationKit', a library of +non-graphical objects; the `AppKit', a library of objects usful in +creating graphical applications; and `Display Postscript', an interface +for drawing to the screen using the PostScript graphics language. + + You can obtain a copy of the OpenStep standard from the GNUstep web +site or it's mirror sites. + +What platforms does GNUstep run on? +----------------------------------- + + Well tested current builds: + Ix86/GNU-Linux + PPC/GNU-Linux + Recent builds - + Ix86 Unixware-2.? Ix86 FreeBSD-3.0 (ELF) Ix86 OpenBSD-2.4 (static + libraries) Sparc SUNOS-4.1.3 PowerPC GNU/Linux + + Probably a few days porting to any other Unix system where current +gcc/egcs compilers and gdb debugger work. See the GNUstep-HOWTO file or + for more +machines. + +Does GNUstep run on Windows? +---------------------------- + + The primary targets for GNUstep are free 'Unix' platforms such as +GNU/Linux. + + That being said, the base library should run on Windows-NT,98 with +the Cygwin unix emulation library from Cygnus +(http://sourceware.cygnus.com/cygwin/) or the MinGW libraries. At +present there are a few problems with networking (Distributed Objects) +support, but the library is believed to work. + + The gui library needs a win32 backend library to work under +Windows-NT. The backend library is a thin layer that converts the +GNUstep methods to handle drawing of GUI elements to calls to the win32 +api. This is a project looking for a volunteer. + + The application-wrapper used for GNUstep already allows for multiple +binaries to be stored for different systems, so you should be able to +write once, deploy anywhere. + +What is GNUstep's position towards KDE and the GNOME project? +------------------------------------------------------------- + + You can use GNUstep with GNOME and/or KDE. GNUstep displays on top +of X11. You can still do programming in C (since Objective-C is just a +superset of C), and when (if?) GCC gets around to it, you'll be able to +mix C++ and Objective-C code in the SAME file. + + GNUstep, is much more than a window manager or desktop environment. +It frees you to develop cross-platform applications without the work of +developing an OS independent framework from scratch. It gives you lots +of basic functionality, from Font Panels to Unicode strings to +Distributed Objects. + +Is the Objective C API for GTK related? +--------------------------------------- + + No. GNUstep applications provide their GUI via the OpenStep API, +which provides fully object-oriented access to GUI manipulation. + + The object-oriented nature of the libraries and language make it +much easier for new users to create their own subclasses rather than +simply using the supplied widgets as in other frameworks. + +How about implementing parts of the Application Kit with GTK? +------------------------------------------------------------- + + Yes and No - The GNUstep architecture provides a single, +platform-independent, API for handling all aspects of GUI interaction +(implemented in the gstep-gui library), with a backend architecture +that permits you to have different display models (display postscript, +X-windows, win32, berlin ...) while letting you use the same code for +printing as for displaying. Use of GTK in the frontend gui library +would remove some of those advantages without adding any. + + That being said, a backend library could be implemented using gtk if +anyone wanted to do so. Since the frontend library handles most of the +work involved in implementing the OpenStep API, the backend is a +relatively thin layer and the advantages of GTK over direct xlib or +win32 calls is likely to be minimal. If/when GTK is ported to more +systems, a backend written using it could be a valuable asset - +volunteers are, as always, wecome. + +Which compiler can I use? Where can I get it? +--------------------------------------------- + + Use gcc-2.8.1 or later, from any GNU ftp site or, on some platforms +you must use egcs-1.1.1 or later, from http://egcs.cygnus.com/ + +Which Foundation Library can I use? +----------------------------------- + + That depends ... + + If you only want to use the database package - gnustep-db, you can +use either the gnustep base library or libFoundation. + + If you want to develop/use GNUstep gui applications, you must use +the gnustep-base library since libFoundation is (13-Feb-2000) missing +much essential functionality. + +How do you use the gnustep-make package? +---------------------------------------- + + Good question. Read the tutorials at the GNUstep web site. Also, +use the makefiles in the libraries, tool directories, and test +applications as examples. + +How can I get GNUstep? +---------------------- + + Get the HOWTO from + Get the +latest release from . If you're really +adventurous, get the latest snapshot by anonymous ftp from + + + Use anonymous CVS to keep up to date - instructions are in the HOWTO. + +How do you run GNUstep? +----------------------- + + You are presumably under the misapprehension that GNUstep is some +sort of window manager. + + It isn't. + + GNUstep is a whole load of things - primarily a set of libraries for +developing software. + + At present, it's those libraries, plus various command-line based +support tools and service providing daemons. In the future, it will be +the libraries, plus the support tools, plus various GUI development +tools, a GUI desktop/workspace application etc. + + At no stage will you ever 'run' GNUstep - you will run applications +and tools and will make use of it's services (though at some point you +may well find packages distributed as 'GNUstep' systems in the way that +you get 'Linux' systems packaged today). + + Current tools are - + + The makefiles package + To make building GNUstep tools and apps simple. + The 'openapp' script + To start up a GUI application from the command line. + The defaults tools + To read, create, delete, and modify user defaults from the command + line. + The name server + To permit applications and tools to locate each other and + communicate. + The pasteboard server + To permit cut-and-paste, drag-and-drop, and to let applicationsm + and tools transparently provide services to each other. + The distributed notification center + To permit applications and tools to be notified of arbitrary + external events. + The 'make_services' program + To locate (and cache information about) applications that are + willing to provide services to other applications. + The 'set_show_service' program + A command-line utility to determine what services an application + should be permitted to offer on it's 'services' menu. + + If you want to see a sample GUI application running - you need to +build GNUstep for use with the 'xgps' library (configuring it with with +the option -with-library-combo=gnu-gnu-gnu-xgps) and look at the +example applications in the gstep-examples package. Build 'Finger' or +'Ink' and start it with 'openapp Finger.app' or 'openapp Ink.app' + + To look best - use WindowMaker (the currently preferred GNUstep +window manager) as your window manager. + +Is there a web site? +-------------------- + + See http://www.gnustep.org/ - the main web site. + +When is GNUstep intended to be available? +----------------------------------------- + + It's usable now (for an experienced developer). Releases are made +about every six months. However, if you are a serious developer, it's +probably best to use the latest snapshots. See the GNUstep web site +for a release schedule. + +What is usable? +--------------- + + gstep-make does pretty much what the makefiles in NeXTstep do. +gstep-base (Foundation) stuff should work fine for almost all projects. +gstep-db is only EOF-1.0 compatible but should work ok. gstep-gui +(AppKit) is usable with the xgps backend, and you would probably have +to fix some things in the gui library. Cut-and-paste works, services +work, drag-and-drop works, the NSText classes partially work. +gstep-xgps basic functionality is quite usable. gstep-xdps is mostly +usable. DGS (Display Ghostscript) is usable but slow. + +Compiling and Developing +======================== + +Can I run NeXT OPENSTEP or Apple Rhapsody programs on GNUstep? +-------------------------------------------------------------- + + You can't run these programs on GNUstep, but if you have the source +code for the programs, you should be able to port them to GNUstep and +compile them. Whether or not you will be able to run them depends on how +complete GNUstep is at the time. + +Is it easy to port OPENSTEP and Rhapsody programs to GNUstep? +------------------------------------------------------------- + + It is probably easy for simple programs. You'll have to use nfmake + to translate the PB.prject file to GNUstep +Makefiles, or rewrite the Makefiles yourself. You will also have to +translate the NIB files (if there are any) to GNUstep model files using +the nib2gmodel program (from +). + +Is there an Interface Builder for GNUstep? +------------------------------------------ + + There is an Interface Builder for GNUstep called Gorm, but it is in +alpha release, so it may not work perfectly. You can get it from the +GNUstep CVS repository (cvs -z3 checkout Gorm). The Project Manager +ProjectCenter is also new. + +Can I use my original NIB files? +-------------------------------- + + No - NeXT/Apple never documented their nib format, so GNUstep +supports both the 'gmodel' format (which stores information as text +(property-lists) and can therefore be edited 'by hand') and binary +archive format (which can be edited by Gorm). There IS a conversion +tool that can be compiled under OPENSTEP to convert OPENSTEP nib files +to GNUstep gmodel files. + +Will code without NIB files work? +--------------------------------- + + Well, GNUstep implements the OpenStep API, not the old NeXTstep API +but, Yes - once the gui library is complete, OpenStep or MacOS-X code +should work without translation under GNUstep. + +Is GNUstep following Apple's Changes to OpenStep? +------------------------------------------------- + + Yes - gstep-base already contains the documented changes in the +Foundation library. GNUstep aims to be compatible with both the +OpenStep specification and with MacOS-X It should be easy to write an +application that compiles cleanly under both GNUstep and Yellow Box. + +Do we have to have the NeXTstep look and feel? +---------------------------------------------- + + Gnustep is aiming for something like the NeXTstep-3.3 look and feel +This is mostly determined by the gui backend library. In the case of +the two existing backends (xdps and xgps), both are designed to look +like NeXTstep/OPENSTEP. If someone wants to write a backend with a +different look, they can. This would only be a few man-months work. + +Can one use the hybrid "Objective-C++" +-------------------------------------- + + that one could on the NeXT? + + No - at present the GNU compiler (gcc or egcs) does not support +"Objective-C++" There are no specific plans to make it do so, but any +volunteers to do it would be welcome. + +Is there a plan to support the Java/YellowBox Bindings? +------------------------------------------------------- + + Yes. The GNustep Java library/bridge called JIGS is available now. +JIGS is a free (LGPL) Java Interface for GNUstep; it can automatically +wrap Objective-C libraries based on GNUstep making them accessible +directly to the Java programmer as if they were Java libraries. As a +side effect, it is also possible to use the whole engine in the reverse +way: JIGS provides a high level API to allow Objective-C programmers to +start java virtual machines inside GNUstep Objective-C code and access +java objects in the java virtual machine transparently, as if they were +objective-C objects. + +What if I compile GNUstep under OPENSTEP/MacOS X Server? +-------------------------------------------------------- + + No - GNUstep uses the X-windows display postscript extension - the +interface to that is not the same as the interface to the +OPENSTEP/MacOS-X windows server. While someone could write a backend +library to provide the interface, nobody has bothered to date. + + Also - there is no known recent port to OPENSTEP of the base library. + +How can I help with GNUstep? +---------------------------- + + 1. Write/debug library code 2. Write documentation 3. Update the +TODO list and library headers 4. Write applications + + Some general advice - + + Let people know what you are doing. Break your project up into the +smallest units you can. Feed back frequent updates to the maintainers. +Ask questions in the discussion mailing list. + + Do remember that any changes beyond a few lines of code (or +documentation) require a disclaimer or copyright assignment to the Free +Software Foundation before they can be incorporated into the project. +Get in touch with the maintainer of the library you are working on +about this. + + Don't start with large-scale reorganisation of anything - instead, +get a general idea in mind of what you want to do, and proceed as much +as possible with incremental changes that don't break anything - that +way you can make those incremental changes available to the rest of the +community at frequent intervals. + + Don't be afraid to give up - there is no shame in finding out that +you have take on too large/complex a project. It's much better to +'resign' and take on a smaller job than to just stop without telling +anyone. + +How do I start writing code? +---------------------------- + + There is plenty of unimplemented stuff in the gui library and +backend libraries that volunteers can work on - just browse through the +code and see if it conforms to the documentation. + + Specific tasks are noted in the developers section on the +www.gnustep.org website. + + Once you have coded something, you could always write a testcase and +documentation for it :-) + +How do I start writing documentation? +------------------------------------- + + Our documentation format is called gsdoc, which is an SGML format +for Objective-C documentation in the same vein as XML. We are also +trying to use Autodoc to self document source code. The gsdoc +translator is included with the base library. + + Newcomers could write documentation for individual classes by +comparing the OpenStep specification, the MacOS-X documentation, and +the GNUstep source. Documentation should clearly note where individual +methods are specific to OpenStep, MacOS-X or are GNustep extensions. + + More experienced people could write documentation on general +programming topics, and tutorials for new users. + + Anyone willing to write documentation, either tutorials for using +GNUstep, or reference documentation for individual classes, should +either write it in gsdoc or as plain ascii text for someone else to +format into gsdoc. + + GNUstep documentation should have copyright assigned to the Free +Software Foundation. + +How do I update the task list? +------------------------------ + + The task list () is +supposed to tell people what jobs are waiting to be done. + + One job of major importance that pretty much anyone can do is to +look for jobs to add to the task list. In the case of methods from the +OpenStep specification or the MacOS-X documentation not being present +in the GNustep libraries, it is also helpful to add the method +prototypes to the library header files. + + At the moment, send changes to Adam Fedor or Richard +Frith-Macdonald + + We are hoping to have a system where people can update the list +directly. + + A beginner can look through the MacOS-X documentation, the OpenStep +specification and the GNUstep source and contribute TODO items. + + If a class or method is in MacOS-X and OpenStep but is not in +GNUstep - it's a high priority TODO and should at least be added to the +GNUstep headers and a dummy version added to the source with a FIXME +comment. + + If a class or method is in MacOS-X but not OpenStep or GNUstep - +it's a low priority TODO. It should be added to the GNUstep headers +bracketed in `#ifndef STRICT_OPENSTEP' + + If a class or method is in OpenStep but not in MacOS-X or GNUstep - +it's a low priority TODO. It should be added to the GNUstep headers +bracketed in `#ifndef STRICT_MACOS_X' + + There are a couple of people working on this already, so it's a good +idea to get in touch with Adam or Richard to coordinate efforts. + +How do I start writing tests? +----------------------------- + + You can write testcases - where the libraries fail tests, you could +either fix the problem, or add it to the task list. + + To write testcases, you need to use anonymous CVS to install the +latest gstep-core snapshot you can find. Then checkout the 'tests' +module from CVS. In the 'tests' directory, you will find a regression +testing framework for gstep-base. In order to use this you will also +need a recent (v 1.3.2 or later) copy of Guile (you can get this from a +GNU ftp site) and will need to hacke checked out, built, and installed +the 'guile' package from the GNUstep CVS repository. + + At present, there is no such framework for the gui library - If you +are interested in working on one, contact + +How do I start writing applications? +------------------------------------ + + You can either look at the links on the GNUstep website for +applications that have been started, and email their owners to +volunteer to help, or you can start your own project. + + If you are starting your own project, you need to - 1. Get the +latest snapshot of GNUstep and build it to use the 'xgps' or 'xdps' +backend library. 2. Look at the example applications (particularly +Ink.app) in the gstep-examples package directory as a basis for your +work. 3. Be prepared to a) ask for help on the gnustep-discuss +mailing list b) fix bugs and implement missing functionality in the +gui and xgps libraries. + +How can I help with the GNUstep website? +---------------------------------------- + + Talk to Adam Fedor , the maintainer. + + The GNUstep website is kept as a CVS module, but the largest portions +of it (the FAQ, the TODO list, and the Documentation) are actually +generated from files in the individual GNUstep packages. + + If you want to update the FAQ or TODO list or documentation - grab +the latest snapshot of the GNUstep core you can find, update it from +the CVS repository, and work with the contents of the appropriate +documentation directory. + + If you want to work on other parts of the website - capture the +pages you want to edit in your web browser (at http://www.gnustep.org). +If you can't do that, you can grab a copy of the website via anonymous +CVS - + + $ CVSROOT=:pserver:anoncvs:@cvs.net-community.com:/gnustep-www + $ export CVSROOT + $ cvs login (password anoncvs) + $ checkout -z3 www + + The main task with the website is to figure out which bits are +out-of-date (or wrong) and update/mark-as-outdated as required. + + Current status - + + The 'developers section' of the FAQ is being worked on by +, and we are looking at rewriting the more +general parts of the FAQ. + +How do I compile GNUstep on my machine? +--------------------------------------- + + Read the file `GNUstep-HOWTO', which comes with the GNUstep +distribution, and also is available separately on the GNUstep ftp +sites. A PDF version also exists on the web site called +`GnustepInstall.pdf'. + +Are there any precompiled packages available? +--------------------------------------------- + + Check for links to +sites with RPMS, and perhaps in the future, Debian packages. In some +cases. You can check the debian site for preconfigured GNUstep packages. + +I get an error compiling mframe.m in gnustep-base. +-------------------------------------------------- + + This occurs on some GNU/Linux systems. You'll need to change the +optimization level, usually like this: + make OPTFLAG=-O + +GNU Objective C Compiler and Objective C Runtime Library +======================================================== + +What is the Objective C Runtime Library? +---------------------------------------- + + The Objective C Runtime Library provides C functions and data +structures required to execute an Objective C program. + + The GNU Objective C Runtime Library offers everything NeXT's runtime +does, including Categories, Protocols, `+poseAs:', thread-safety, class +initialization on demand, delayed loading of classes, and +initialization of static instances (such as @""-style string objects). + + It also has several improvements over NeXT's implementation: + + * NeXT's runtime requires an extra function call (objc_msgSend) for + each message that is sent; (the function looks up the receiving + instance's implementation of the method). GNU's implementation is + faster because it does not use an extra function call. Instead, it + inlines a short piece of code that makes two pointer hops into a + method dispatch table; because the code is inlined, it does not + incur the overhead of a function call. + + * When running in thread-safe mode, NeXT's runtime must aquire a + global mutual exclusion lock every time a message is sent; this is + extremely slow. GNU's runtime, amazingly, sends messages just as + fast in thread-safe mode as it does in single-thread mode--the + code path does not contain even a single extra instruction! The + GNU runtime only needs locks when certainly structures are + written, not read; the structures are written relatively + infrequently: only at class initialization and when `+poseAs:' is + called. + + * GNU's runtime provides "selector-types" along with each selector; + NeXT's does not. A selector-type is a string that describes the C + variable types for the method's return and argument values. Among + other uses, selector-types is extrememly helpful for fast + distributed objects implementations, (see GNUstep Base Library + Section, below). + + * Many of the GNU functions have different names than their + corresponding NeXT functions; the GNU names conform to the GNU + coding standards. + + * GNU's runtime library has a new class heirarchy manipulating + method called `-transmuteClassTo:'. It can change the class of an + instance to a cousin class of the same instance-size. + + * NeXT's compiler, `cc', is based on an old version of `gcc'. GNU's + compiler is, of course, the latest version of `gcc', and therefore + contains all the latest enhancements. + + +Does it allow a mixture of Objective C and C++? +----------------------------------------------- + + No. Unlike NeXT's `cc', GNU GCC does not support source files +containing both Objective C and C++. People at Cygnus have mentioned +that they would be willing to do the work--if they were paid for it, of +course. Several people are interested in seeing this happen. Send +email to `discuss-gnustep@gnu.org' if you are interesting in pushing +this issue, so that the efforts of all those people interested can be +coordinated. + + Also, unlike NeXT's `cc', GNU GCC does not support the `extern +"Objective-C"' construct. + +Where can I find more information? +---------------------------------- + + The FAQ associated with the newsgroup `comp.lang.objective-c' +contains more information about GNU Objective C. + +GNUstep Base Library +==================== + +What is the GNUstep Base Library? +--------------------------------- + + The GNUstep Base Library is a library of general-purpose, +non-graphical Objective C objects. For example, it includes classes +for strings, object collections, byte streams, typed coders, +invocations, notifications, notification dispatchers, moments in time, +network ports, remote object messaging support (distributed objects), +event loops, and random number generators. + + It provides functionality that aims to implement the non-graphical +portion of the OpenStep standard (the Foundation library). + +What is its current state of development? +----------------------------------------- + + It is about 98 percent of the way to having all the OpenStep classes +(and the later OPENSTEP/Rhaspody classes) fully implemented. Normal +work can already be done using the library since the missing 2 percent +are the least-often-used features or are simply not up to date with the +latest MacOS-X spec. Over 60,000 lines of code have already been +written. + +What are the features of GNU Distributed Objects? +------------------------------------------------- + + GNU Distributed Objects has many of the features of other distributed +objects implementations, but, since it is free software, it can be +ported to platforms for which other distributed objects implementations +are not available. + + [NOTE: The GNU distributed object facilities have the same +ease-of-use as NeXT's; be warned, however, that they are not compatible +with each other. They have different class heirarchies, different +instance variables, different method names, different implementation +strategies and different network message formats. You cannot +communicate with a NeXT NSConnection using a GNU Connection. + + Here are some differences between GNU distributed objects and NeXT's +distributed objects: NeXT NSDistantObject asks it's remote target for +the method encoding types and caches the results; GNU NSDistantObject +gets the types directly from the local GNU "typed selector" mechanism +if the information is known locally and only queries the remote target +or caching encoding types when using a method that is not known to the +local process. The NSProxy for the remote root object always has name 0 +and, once set, you cannot change the root object of a NSConnection; the +GNU Proxy for the remote root object has a target address value just +like all other Proxy's, and you can change the root object as many +times as you like. ]. + +GNUstep GUI Library +=================== + +What is the GUI Library? +------------------------ + + The GNUstep GUI Library is a library of objects useful for writing +graphical applications. For example, it includes classes for drawing +and manipulating graphics objects on the screen: windows, menus, +buttons, sliders, text fields, and events. There are also many +peripheral classes that offer operating-system-independent interfaces to +images, cursors, colors, fonts, pasteboards, printing. There are also +workspace support classes such as data links, open/save panels, +context-dependent help, spell checking. + + It provides functionality that aims to implement the `AppKit' +portion of the OpenStep standard. However the implementation has been +written to take advantage of GNUstep enhancements wherever possible. + +Explain the organization of the front- and back-ends +---------------------------------------------------- + + The GNUstep GUI Library is divided into a front- and back-end. The +front-end contains the majority of implementation, but leaves out the +low-level drawing and event code. A back-end can override whatever +methods necessary in order to implement low-level drawing event +receiving. Different back-ends will make GNUstep available on various +platforms. The default GNU back-end will run on top of X Windows and +the DisplayGhostScript Server. Other back-ends could allow GNUstep to +run on OpenGL, OS/2, and WIN32 graphics/event platforms. Much work +will be saved by this clean separation between front- and back-end, +because it allows different platforms to share the large amount of +front-end code. + +What is the current state of development of the front-end? +---------------------------------------------------------- + + Many of the classes are well implemented, if not thouroughly tested. +See the GNUstep web sites and read status information contained in the +distribution for the most up-to-date information. + +What is the current state of development of the X/DPS back-end? +--------------------------------------------------------------- + + It works, but is slow and buggy. A lot of work could be done. + +GNUstep DisplayGhostScript Server +================================= + +What is the Display Ghostscript Server? +--------------------------------------- + + It is a free implementation of a Display PostScript server based on +the ghostscript program by Aladdin software. + +What is its current state of development? +----------------------------------------- + + GNU contracted with Aladdin software to add some key features to +ghostscript so it could be used as a DPS server. This work has mostly +been done, althought Aladdin did not completely finish the work that +they were contracted for. DGS works fairly well with a single context +and will soon work with multiple contexts. Alpha channel and compositing +currently doesn't work, but should before the end of 2000 (It's already +been fixed in Ghostscript, just not released). + +What is the relationship between the Display Ghostscript Server and X Windows? +------------------------------------------------------------------------------ + + Display Ghostscript runs on top of X Windows. + +All trademarks mentioned on in this FAQ belong to their owners. + diff --git a/GNUstep-HOWTO b/GNUstep-HOWTO new file mode 100644 index 00000000..5c9b7cde --- /dev/null +++ b/GNUstep-HOWTO @@ -0,0 +1,845 @@ + GNUstep HOWTO + ************* + + Last Update: 26 February 2001 + + This document explains how to build the different components of the + GNUstep core libraries. + + Copyright (C) 1996 - 2001 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 or + any later version published by the Free Software Foundation. + +Introduction +************ + + This document explains how to build the GNUstep core libraries. The +core libraries, along with associated tools and other files provide +everything necessary for a working GNUstep system. + + In order to easily compile and debug GNUstep projects, you will need +the GNU Objective-C compiler `GCC' as well as various other GNU +packages. + + You will need at least 80Mb of hard disk space (150Mb prefered) in +order to compile the GNUstep core libraries. + +Summary +******* + + In order to compile the libraries, you need to compile and install +the following packages first (if you don't already have them): + + * gcc (Version 2.8.0 or greater) + + * GNU make (Version 3.75 or greater) + + * The TIFF library (libtiff) (Version 3.4beta36 or greater) + + After installing these packages, get the following individual +packages: + + * gnustep-make + + * gnustep-base + + * gnustep-gui + + * gnustep-xdps + + * gnustep-xgps + + See for information on where to get these +packages. Only one of gnustep-xgps or gnustep-xdps is required. We +currently recommend gnustep-xgps. Other packages you may need to get +depending on the type of system you are using, include: + +`WindowMaker (Version >= 0.62)' + GNUstep and WindowMaker work together to provide a consistant + interface. Although it is not required, GNUstep will work much + better if you use it with the WindowMaker window manager. In + addition, WindowMaker includes some functionality that GNUstep + uses that would otherwise not be available. Get WindowMaker from + . + +`DGS, the XFree86 DPS extension, or Adobe DPS' + If you want to use the features of a Display Postscript + (DPS)backend. Note that it is not required since you can use the + XGPS backend that is Xlib based. Note that the DPS backend is + also still experimental and not recommended. DPS can be obtained + from the following locations: + + * DGS client/server, + + * XFree86 DPS, + + * Adobe DPS, (contact your OS distributor) + +`PCThreads' + For GNU/Linux systems on Intel x86 processors. PCThreads is no + longer necessary (and should not be used) on GNU/Linux systems with + glibc version 2, such as Debian 2.0 and RedHat 5.x and greater. + +`GDB and Objective-C patch' + GDB can be obtained from . The patch to + make it work better with GNUstep can be obtained from + + +`libxml' + The libxml library (Version 2) is used to translate some of the + documentation for GNUstep and to provide suport for MacOS-X + compatible XML-based property-lists. It is recommended but not + currently required. + +`openssl' + The openssl library is used to provide support for https + connections by the NSURL and HSURLHandle classes. It is + recommended but not currently required. + +`libiconv' + Unicode support functions (iconv) come with glibc version 2.1 or + greater. If you don't have this, you can get the separate libiconv + library from < + http://clisp.cons.org/~haible/packages-libiconv.html>. However, + neither one is required to use GNUstep. + +`ffcall libraries' + This is a library that provides stack frame handling for + NSInvocation and NSConnection. This library is highly recommended. + The previous builtin method for stack frame handling is no longer + supported and may be removed in the future. + +`libobjc library snapshot (for gcc version <= 2.95.2)' + This is a special version of the Objective-C runtime that include + several bug fixes and features that have not been officially + released yet. It is available at + which compiles using the + GNUstep Makefile package (so you don't have to get the entire gcc + dist). Make sure to set the THREADING variable in the GNUmakefile. + It might also be best to compile the library static (make + shared=no) and just copy to the place where the gcc libobjc + library is (type gcc -v to get this location). + +Compiling and Installing the packages +************************************* + + Make sure you install all the previously mentioned libraries first +before configuring and building GNUstep (Except you need to install +libobjc after installing gnustep-make, unless your installing it as part +of gcc). + + Note: you will need to be able to install packages as root (at least +the base library) for applications to work correctly. + + For installation on MinGW systems, read the README.MinGW file in the +make package. + +Using a Display Postscript System +================================= + + Install a Display PostScript system if you want to use the XDPS +backend. You do not need it if you want to use the XGPS backend. Some +systems, like Sun Microcomputers(TM) already have a DPS system +installed. Linux/GNU systems need to use a free implementation of DPS +(described in the Introduction.) + + If you are installing DGS, follow the installation instructions +included with the DGS package. If you are installing the XFree86 DPS +extension, follow the instructions included with that package (and note +that you need to be running XFree86 version 4.0 or greater). + +Installing the Core Libraries +============================= + + The GNUstep packages uses the Autoconf mechanism for configuration; +it checks some host capabilties which are used by all GNUstep software. +To configure just type: + + ./configure + + The GNUstep makefile package needs a root directory. If the +GNUSTEP_SYSTEM_ROOT environment variable is set then configure will use +its value as the root directory. You can also specify the root +directory when you run configure with the prefix paramter; the +following command makes /usr/local/GNUstep the root directory: + + ./configure --prefix=/usr/local/GNUstep + + If you do not have the GNUSTEP_SYSTEM_ROOT environment variable set +and you do not specify a root directory when running configure, then +configure will use /usr/GNUstep as the default root directory. + +Alternate Library Setup +----------------------- + + You can specify compilation of alternate libraries by using the +-with-library-combo option: + + ./configure --with-library-combo=gnu-gnu-gnu-xdps + + to compile with the xdps library rather than the default xgps +backend. IMPORTANT: The xdps backend is still experimental. Do not use +it unless you are willing to deal with PostScript problems and other +bugs. + + Read the installation instructions in the Makefile package (make) +for more installation options. Make sure you use the same configuration +options when configuring each GNUstep library. + +Building the Package +-------------------- + + To build the individual packages, use the familiar set of commands +for each pacakge: + + ./configure + make + make install + + Start with the Makefile Pacakge (gnustep-make), then do gnustep-base, +gnustep-gui and finally gnustep-xgps (or gnustep-xdps). After installing +gnustep-make you need to execute GNUstep's shell configuration script, +as follows: + + . /usr/GNUstep/System/Makefiles/GNUstep.sh + + before proceeding any further. + + NOTE: If you are trying to install the packages without root +permission, you need to change one thing in the base library. Edit the +file gnustep-base/Tools/gdomap.h and uncomment the last line. + +Additional Installation +*********************** + + Add the shell script `GNUstep.sh' located in the Makefile package to +your shell startup file (such as `.profile'). For instance: + + GNUSTEP_SYSTEM_ROOT=/usr/GNUstep + export GNUSTEP_SYSTEM_ROOT + . $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh + + in your `.profile' file will work (Note the period at the beginning +of the line). It defines environment variables that are needed to find +GNUstep files and executables. Users of csh need to use the +`GNUstep.csh' script. Read the make package `README' for more info. +Some systems, like GNU/Linux have an `/etc/profile.d' directory where +scripts can be executed automatically. If you want to set up GNUstep +for every user on your system, you can try copying/linking the +`GNUstep.sh' there. For csh or tcsh, try + + setenv GNUSTEP_SYSTEM_ROOT /usr/GNUstep + source $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.csh + + Set up your home GNUstep directory. This is where user defaults are +kept, and in the future, other files may be kept there. + + cd + mkdir GNUstep + + Next, set your local time zone. There are four ways to do this, pick +one (see `$GNUSTEP_SYSTEM_ROOT/Libraries/Resources/NSTimeZones/zones' +for typical time zones): + + 1. Use the defaults utility to set "Local Time Zone" to your local + time zone (defaults is installed with GNUstep in the Tools + directory). Type something like "defaults write NSGlobalDomain + "Local Time Zone" GB". + + 2. Set the GNUSTEP_TZ environment variable. + + 3. Create the file + `$GNUSTEP_SYSTEM_ROOT/Libraries/Resources/NSTimeZones/localtime' + with the name of the local time zone in it. + + 4. Set the TZ environment variable (this may conflict with other + software on your system though). + + If you are using a built-in DPS server, you may need to set the +PSRESOURCEPATH environment variable (on Solaris, it's set to +`/usr/openwin/lib/X11'). + + Set up your system to execute some GNUstep deamons. If you don't do +this, they will be started automatically when you run your first +GNUstep app: + + * gdomap - Put this in a system startup file, like `/etc/rc.local' + or `/etc/rc.d/rc.local' (customize for your system) + GNUSTEP_SYSTEM_ROOT=/usr/GNUstep + if [ -f $GNUSTEP_SYSTEM_ROOT/Tools/powerpc/linux-gnu/gdomap ]; then + $GNUSTEP_SYSTEM_ROOT/Tools/powerpc/linux-gnu/gdomap + fi + + * gdnc - Put this after executing `GNUstep.sh' in your local .profile + + * gpbs - Put this after executing `GNUstep.sh' in your local .profile + + if [ `gdomap -L GDNCServer | grep -c Found` == '0' ]; then + echo "Starting GNUstep services..." + gdnc + gpbs + fi + +Test Tools and Applications +*************************** + + Test programs for the base library are in `base/Testing'. Example +applications are located in the gstep-examples package. To make these, +just uncompress and untar this package, cd to the appropriate +directory, and type make. Generally you will need to install GNUstep +first before doing this. + + To run the examples. Use the openapp utility that is part of the +GNUstep makefile package (and stored in `$GNUSTEP_SYSTEM_ROOT/Tools'). +Usage is: + + openapp [--library-combo=...] application [additional arguments to app] + + Good Luck! + +Machine Specific Instructions +***************************** + + Below is a list of machines that people have attempted to compile +GNUstep on. GNUstep compiles with little or no trouble on many of the +more popular operating systems. Some machines marked with _Unstable_ +may have some trouble or may not work at all. + + A recommended compiler is listed for each machine, if known. You +should try to use the recommended compiler for compiling GNUstep, as +GNUstep is quite complex and tends provoke a lot of errors in some +compilers. Even versions newer than the listed compiler may not work, +so don't just get the latest version of a compiler expecting it to be +better than previous versions. + + If you have compiled GNUstep on a specific machine, please send +information about what you needed and any special instructions needed +to the GNUstep maintainer . + + If your having mysterious trouble with a machine, try compiling +GNUstep without optimization. Particularly in the newer GCC compilers, +optimization can break some code. The easiest way to do this is when +configuring: `CFLAGS="" ./configure'. Or `make OPTFLAG=""'. + +Debian/DEC-Alpha +================ + +`Recommended compiler' + Unknown + +`Extra libs needed' + Unknown + +`Special Instructions' + Unknown + +FreeBSD 3.x +=========== + + Compiles "out of the box" on FreeBSD 3.4. + +`Recommended compiler' + gcc 2.95.2 + +`Extra libs needed' + Unknown + +`Special Instructions' + You need to use gmake not make to compile the GNUstep packages. A + special port of gdb can be used with the Objective-C patches from + + + The best compiler for GNUstep is the latest release of the GNU + Compiler Collection (GCC). You can find it at + . + + If you want to use the native POSIX threads support from `libc_r' + pass `--enable-threads=posix' to configure. This is the + recommended option as this is the FreeBSD threads package that + gives the best results -with others you may be unable to run some + examples like `diningPhilosophers'. + + The whole compilation process can fail if you have another threads + library installed so watch out for installed packages like `pth' + and such. Besides the support for libc_r, GNUstep will also look + for `pth' and `pcthreads', so if you have installed them and they + aren't detected prepare to write a nice bug report. + + This can be done more much easily by using the port version. Just + `cd' to `/usr/ports/lang/egcs' and do a `"make WANT_THREADS=yes + install"'. Easy. + + If configure cannot find tiff.h or the tiff library and you have + it installed in a non-standard place (even `/usr/local'), you may + need to pass these flags to configure: + `CFLAGS="-I/usr/local/include"' and `LDFLAGS="-L/usr/local/lib"'. + +FreeBSD 2.x (_Unstable!_) +========================= + +`Recommended compiler' + gcc 2.8.x + +`Extra libs needed' + Unknown + +`Special Instructions' + Only static libraries work on this system. Use /stand/sysinstall + to install these packages if you have not already done so: + + gmake (GNU make) + gcc 2.8.x + + Seems to compile ok, but some tests crash. Possibly due to a + performace 'hack' in base. Might be a good idea to upgrade to + FreeBSD 3.x. You need to use gmake not make to compile the + GNUstep packages. + +GNU-Linux/Intel (RedHat 5.x, 6.x, and 7.0) +========================================== + +`Recommended compiler' + With 5.x, the egcs compiler that comes with RedHat. Later versions + may have gcc installed, although 7.0 comes with a snapshot of gcc + (called 2.96) which is unsuitable for compiling Objective-C code. + For 7.0 you should install the egcs compatibility packages (or an + official gcc release). + +`Extra libs needed' + Unknown + +`Special Instructions' + Make sure you have a decent version of the compiler. Try `cc -v' + or `gcc -v' to get the version of the compiler. With 5.x, make + sure you set CC=egcs before configuring, as in: + + export CC=egcs + configure .... + + Since RedHat 5.x also comes standard with an old version of gcc. + + On RedHat 7.0, configure like this + CC=egcs LDFLAGS="-u shmctl@GLIBC_2.2 -L/lib -lc -u getpwuid_r@GLIBC_2.1.2 + -L/lib -lc -u getpwnam_r@GLIBC_2.1.2 -L/lib -lc" ./configure + +GNU-Linux/PowerPC (LinuxPPC 4.x) +================================ + +`Recommended compiler' + egcs-2.90.25 980302 (egcs-1.0.2 prerelease). glibc-0.961212-1h. + gdb: 4.16.97. + +`Extra libs needed' + None. + +`Special Instructions' + egcs-1.1.2 does NOT work. + +GNU-Linux/PowerPC (LinuxPPC 5.x) +================================ + +`Recommended compiler' + egcs-1.1.2 (default compiler), or gcc-2.95 + +`Extra libs needed' + None. + +`Special Instructions' + You need to compile without optimization or the compiler will not + be able to compile several files (CFLAGS="" ./configure). Compiling + with CFLAGS="-O" also works. The gcc-2.95 compiler fixes this + problem. There may be a problem with the X server that causes + programs to crash with a X_QueryColors error. If so, get a newer X + server at + . + + Invocations (and DO) do not work well. The major problem is sending +data with data sizes less than 4 bytes (chars, shorts, etc). To fix +this, we recommend using the ffcall libraries via the `--enable-ffcall' +option when configuring (Read the instructions on this in the +configuration section). + +Irix 6.4/MIPS (_Unstable!_) +=========================== + +`Recommended compiler' + Unknown + +`Extra libs needed' + Unknown + +`Special Instructions' + Not ported at all to this machine. Might be better now, but no + current testing. Some files don't compile - get internal compiler + errors using gcc 2.8.1. + +MkLinux/PowerPC (MkLinux DR 3) +============================== + +`Recommended compiler' + egcs-2.90.25 980302 (egcs-1.0.2 prerelease) which comes standard + with DR 3. + +`Extra libs needed' + None. + +`Special Instructions' + Comes with a good version of gcc. Seems to compile and install + ok, althouth DR3 has an old version of glibc, which requires some + workarounds which should be taken care of in the configuration. + Not completely tested, so some aspects, particular object + invocations and DO may not work properly. + + If you want threads, you'll probably have to get the latest gcc + compiler and glibc library (which has the threads library) and + install both. + +NetBSD +====== + +`Recommended compiler' + Unknown + +`Extra libs needed' + Unknown + +`Special Instructions' + Can compile with shared libraries on elf architectures, although + problems persist with the NXConstantString class. Currently, to + avoid this you can redefine NXConstantString to NXConstantString2 + in the libobjc library. Or you could do the following (works on + NetBSD 1.4Z) + + cd /usr/lib + ar -dv libobjc_p.a NXConstStr.po + ar -dv libobjc_pic.a NXConstStr.so + ar -dv libobjc.a NXConstStr.o + rm /usr/lib/libobjc.so.0.0 + +Netwinder (_Unstable!_) +======================= + +`Recommended compiler' + Build #12 of the system. + +`Extra libs needed' + Unknown + +`Special Instructions' + See + +OpenBSD 2.x (_Unstable!_) +========================== + +`Recommended compiler' + Unknown + +`Extra libs needed' + Unknown + +`Special Instructions' + Can only compile with static libraries. Gives a lot of warnings + + GNUstep 0.6.0 uses code to access the /proc filesystem, which may + be broken on BSD machines. To avoid this configure with the + argument -enable-fake-main. Later versions of GNUstep should + check for a broken /proc filesystem. + +OSF Alpha (_Unstable!_) +======================== + + Information is for Version 3.2C + +`Recommended compiler' + egcs-1.1.1/1.1.2, gcc-2.95 + +`Extra libs needed' + Unknown + +`Special Instructions' + Can only compile with static libraries. Compiler may fail when + linking executables (e.g. gdnc). Standard ranlib and ar programs + are to feable to create libraries. Should use GNU binutils + versions. Linker sometimes fails to find symbols, in which case + you may need to link with a library twice. For instance, add an + extra -lgnustep-xgps in ADDTIONAL_TOOL_LIBS in the + GNUmakefile(.preamble). + +Solaris 2.5.1/Sparc +=================== + +`Recommended compiler' + Unknown + +`Extra libs needed' + tiff, Don't use the one in /usr/openwin + +`Special Instructions' + See the Solaris 2.6 section for more instructions. + +Solaris 2.6/Sparc +================= + +`Recommended compiler' + egcs-2.91.60 (1.1.2?), egcs-1.0.1, gcc 2.8.1, gcc 2.95.2 + +`Extra libs needed' + tiff, Don't use the one in /usr/openwin + +`Special Instructions' + GCC 2.8.0 induced a problem on Solaris/Sparc systems; however, + there is a patch to fix this in the contrib directory on the ftp + sites (This is also true for all versions of gcc/egcs up through + 2.95.2 (possibly fixed in later versions)). + + To avoid using the tiff library in /usr/openwin, configure like + this: + LIBS=-L/usr/local/lib ./configure + if, for instance, you have put a newer tiff library in + /usr/local/lib + + Even with the about patch, invocations (and DO) still don't work +well. The major problem is sending messages with more than four +arguments. We recommend using the ffcall libraries via the +`--enable-ffcall' option when configuring (Read the instructions on +this in the configuration section). + + If you are using threads, make sure the Objective-C runtime (libobjc +that comes with gcc) is compiled with threads enabled (This is true by +default) AND that it is compiled with the _REENTRANT flag defined (This +does not seem to be true by default). + +Solaris 2.7/Intel +================= + +`Recommended compiler' + egcs 1.1.2 + +`Extra libs needed' + Unknown + +`Special Instructions' + Make sure there are no -g compiler flags (specify `CFLAGS= + ./configure', when configuring) or remove it from `OPTFLAG' + make/config.make. You will probable get a lot of text relocation + warnings, which probably can be ignored. See the other Solaris + instructions above for more information. + +Suse 6.x/Intel +============== + + GNUstep has been tested on version 6.2-6.4 of Suse + +`Recommended compiler' + Standard + +`Extra libs needed' + None + +`Special Instructions' + It seems that there is a problem with the default kernel build + distributed with Suse which means that the socket binding used by + gdnc doesn't work. If you recompile the kernel then it starts + working. + +Suse 7.x/Intel +============== + + GNUstep has been tested on version 7.0 of Suse + +`Recommended compiler' + Standard + +`Extra libs needed' + None + +`Special Instructions' + See the instructions for Suse 6.x + +Unixware-2.1.3/Intel +==================== + +`Recommended compiler' + Unknown + +`Extra libs needed' + Unknown + + Special Instructions for GNUstep installation on Unixware 2.1 systems + +1 + Tune the kernel to increase the argument space so that we can pass + long command-line argument strings to processes (which the + makefiles do) (/etc/conf/bin/idtune ARG_MAX 102400) + +2 + Install raft of the latest GNU software + + gzip (you need this to unpack other stuff) + make (to build everything) + m4 (for autoconf etc) + autoconf (if you need to change anything) + bison + flex + binutils (required by gcc if you want to debug) + gcc-2.8.1 + (configure --with-gnu-as --with-gnu-ld --with-stabs) + NB. gcc-2.8.1 needs a fix to __do_global_dtors_aux() + in crtstuff.c on Unixware 2.1.3 + (and possibly other unixware versions) + The fix is already in recent versions of egcs. + + ================================== + static void + __do_global_dtors_aux () + { + static func_ptr *p = __DTOR_LIST__ + 1; + static int completed = 0; + + if (completed) + return; + + while (*p) + { + p++; + (*(p-1)) (); + } + + #ifdef EH_FRAME_SECTION_ASM_OP + __deregister_frame_info (__EH_FRAME_BEGIN__); + #endif + completed = 1; + } + ====================================== + +3 + Having got gcc working - it's probably a good idea to rebuild all + your GNU software using it! + +4 + Build gstep as normal. + +5 + The SIOCGIFCONF ioctl sometimes doesn't work on unixware after + applying some of the OS patches. + + So I have added a '-a' flag to gdomap to give it the name of a file + containing IP address and netmask information for the network + interfaces on the system. + + You need to set up a file (I suggest '/etc/gdomap_addresses') + containing the information for your machine and modify your system + startup files in /etc/rc?.d to run gdomap, telling it to use that + file. + + eg. If your machine has an IP address of '193.111.111.2' and is on + a class-C network, your /etc/gdomap_addresses file would contain + the line + + 193.111.111.2 255.255.255.0 + + and your startup file would contain the lines + + . /usr/local/GNUstep/Makefiles/GNUstep.sh + gdomap -a /etc/gdomap_addresses + + If you don't set gdomap up correctly, Distributed Objects will not +work. + +Windows with CYGWIN (_Unstable!_) +================================= + +`Recommended compiler' + gcc 2.95.2 (Cygwin release 1.1.2 or later) + +`Extra libs needed' + Objective-C library DLL + () for shared libs. + +`Special Instructions' + Static libs require no extra effort (just make shared=no), + however, DLLs (shared=yes) are compiled by default, and for this + you need a special version of the Objective-C library that also + compiles as a DLL. Make sure files and compilation done in Unix + mode (no ^M in files). Due to some interesting dependancies, it is + recommended that you compile and install each sub-package (make, + base, etc) independantly. Gdomap services not set up correctly. + Must add services lines to `C:\WINDOWS\services' (on Windows 98) + or xxx (on Windows NT). Base library only. No native GUI backend. + +Getting Libraries via Anonymous CVS +*********************************** + + If you didn't get one of the snapshots, or if you want to be sure to +stay on the bleading edge, then you should get the core via CVS: + + The quick and painless CVS tutorial (by michael hanni (slightly +modified) + + First, set the CVSROOT environment variable. If you are using +bash/sh you can do something like this at the prompt: + export CVSROOT=":pserver:anoncvs@cvs.net-community.com:/gnustep" + + Second, if this is the first time loging into the CVS server: + cvs login + + You should get a password prompt soon after: + (Logging in to anoncvs@cvs.net-community.com) + CVS password: + + Enter the password `anoncvs'. This should return you to your prompt. +From here you can checkout any module in the CVS server you like. To +checkout a module you do this: + cvs -z3 checkout modulename + + The -z3 merely tells the cvs server to compess everything to a +certain compression level before it sends it to you. + + If you haven't already done so, change to the directory, where you +want the source to reside. + + Next, you want to get the whole core, so you do: + cvs -z3 checkout core + + After you have checked out the source you can compile it as usual. +To update the source, go into the directory of the source tree you want +to update, for example, go into 'xgps', and type: + + cvs -z3 update -Pd + + You don't have to re-checkout after you have the source, just update! +Also try `cvs checkout -c' to get a list of available modules. + +Other Instructions +****************** + +Better debugging with Objective-C runtime +========================================= + + Normally, the Objective-C runtime is compiled with debugging +information, which actually makes debugging of user apps frustrating +because stepping into a method call will actually cause gdb to step +into the internal Objective-C method call mechanism, which you don't +want most of the time. + + The way to avoid this is to compile the Objective-C runtime library +without debugging information. Here's how: + + cd egcs-build-directory/gcc + rm -f objc/*.o + make CFLAGS=-O2 libobjc.a + cp libobjc.a your-egcs-installation-dir + +Acknowledgements +**************** + + Authors: Adam Fedor , + Pascal Forget , + Ovidiu Predescu , + Camille Troillard + Richard Frith-MacDonald + + This file is part of GNUstep. + diff --git a/NEWS b/NEWS index d524f5f4..2ab287d9 100644 --- a/NEWS +++ b/NEWS @@ -1,7 +1,7 @@ NEWS **** -The currently released version is `0.9.0'. +The currently released version is `0.9.1'. Changes in version `0.9.1' ========================== diff --git a/README.MinGW b/README.MinGW new file mode 100644 index 00000000..e95a703a --- /dev/null +++ b/README.MinGW @@ -0,0 +1,121 @@ +Compiling GNUstep on MinGW +========================== + +MinGW is a collection of header files and import libraries that allow +one to use GCC and produce native Windows32 programs that do not rely +on any 3rd-party DLLs. GNUstep has only partially been ported to MinGW +so expect some problems when trying to compile. Also, there are still +subtle problems with running GNU tools on Windows, so any problems you +may encounter may just as easly have to do with the compilation tools +you are using as with GNUstep. + +MinGW on Cygwin +--------------- + +This is the only configuration I've tested so far. This method +uses the Cygwin tools to help out with the configuration and +compilation of the libraries. It's always good to get the very latest +version of Cygwin and MinGW. These instructions were performed with +Cygwin DLL 1.1.4 and MingW gcc 2.95.2-1. If you have more experience +with MinGW than me, please help improve these instructions! + +I assume you have installed Cygwin and MinGW, and dowloaded and +unpacked the GNUstep core package. You also need to download a version +of the Objective-C runtime that compiles as a shared library +(DLL). See the GNUstep-HOWTO file for more information on where to get +various files. + +1. First, start up a Cygwin BASH shell and make sure the MinGW tools +are in your path: + + export PATH=//c/gcc-2.95.2-1/bin:$PATH + +(Put in whatever path you have for the mingw tools). + +2. The default location for GNUstep on Unix systems in /usr/GNUstep, but +there is no default for Windows machines, so you need to set that up +first with the GNUSTEP_SYSTEM_ROOT environment variable. To put it in +a similar location, you might try: + + export GNUSTEP_SYSTEM_ROOT=//c/cygwin/usr/GNUstep/System + +But you can put it anywhere you like (as long as you specify the full +path with the disk label so MinGW can find it). You can also specify this +with configure, using the --prefix=//c/cygwin/usr/GNUstep/System option. + +3. For various reasons, we need to configure and build each +sub-package separately. So first, go to the 'make' subdirectory of the +core package and configure: + + cd make + ./configure --target=i386-mingw32 + +4. Now build the Makefile package. For some reason, the make that comes +with MinGW doesn't like the way GNUstep makefiles are setup (or perhaps +it's that MingW make doesn't work with bash), so use Cygwin's make: + + /usr/bin/make target=i386-mingw32 + /usr/bin/make target=i386-mingw32 install + +5. Now source the GNUstep.sh file so the rest of the packages will +compile correctly: + + . $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh + +6. Now you can compile the Objective-C runtime DLL (unless you already +have one installed): + + cd location_of_the_libobjc_library + /usr/bin/make target=i386-mingw32 + /usr/bin/make target=i386-mingw32 install + +7. Now we can configure and make the base library. + + cd location_of_the_core_package/base + ./configure --target=i386-mingw32 + /usr/bin/make target=i386-mingw32 + /usr/bin/make target=i386-mingw32 install + +Note that the base library is not completely ported to run on MinGW yet. +In particular, the gstep-base DLL doesn't seem to be set up correctly. +To compile the gstep-base as a static library, use: + + /usr/bin/make shared=no + +If you get tired of typing "target=i386-mingw32" all the time, then before +you exec the GNUstep.sh script, just set the GNUSTEP_HOST: + + export GNUSTEP_HOST=i586-pc-mingw32 + . $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh + + +Native MinGW +------------ + +(Information provided by Craig Miskell) + +So far, this configuration only works when compiling the Makefile package +(gstep-make). It should, in the future work on the libraries. First, you +need to get a port of sh (probably zsh) for Windows +(ftp://ftp.blarg.net/users/amol/). + +1. Make sure $HOST_CC or $CC is set to MinGW's gcc. The default seems to be +wrong. + +2. Now configure. You may need to set the installation directory, because +the default installation dir is for Unix machines: + + ./configure --prefix=/usr/GNUstep/System + +(Make sure the drive is specified correctly in the path). + +3. Then make and install + + make + make install + +4. Now source the GNUstep.sh file so the rest of the packages will +compile correctly: + + . $GNUSTEP_SYSTEM_ROOT/Makefiles/GNUstep.sh +