Updated: Proposed GNUstep Filesystem Hierarchy Document.

[Tim Harrison]

Hey all.

Thanks to Martin Brecher for some additions to this proposal.

As before, you can view it at:

http://www.linuxstep.org/documentation/GNUstepFH.html

Also, I'm attaching a copy, as I heard some comments to the effect that 
some people didn't particularly want to open a web browser to have a 
look. :)  So, please pardon my lengthy text attachment.

I look forward to your comments.

--

Tim Harrison
tim@linuxstep.org
http://www.linuxstep.org/

Presented below is the latest update to the Proposed GNUstep Filesystem 
Hierarchy Document, submitted as a proposal to the GNUstep Project.  Comments 
are welcome.





Proposed GNUstep Filesystem Hierarchy Document

Original Date: February 23, 2002
Authors:  Tim Harrison <tim at linuxstep dot org>
          Martin Brecher <webmaster at gnustep dot de> 

Updated:  March 15, 2002
Updated:  April 26, 2002



The GNUstep Domain Hierarchy
============================

On GNUstep you have four sperate places where files related to GNUstep
are installed: these places are called domains.  These four 
domains are the System domain, the Local domain, the Network domain,
and the User domain.  Each of the mentioned domains serves a special 
purpose.  While we will have a detailed look at the directories contained
in each domain, the general purposes of the different domains will be 
explained in the following:



The System domain
-----------------
The System domain is found in the /System folder of your GNUstep 
installation.  This directory contains all files which were included
in the default GNUstep installation or distribution.  Namely these
are the basic GNUstep libraries (Foundation and AppKit), essential
system applications (the Workspace Manager, the Editor, applications
related to system administrative tasks), the developer applications (Project 
Center and Gorm, as well as header files), essential extensions (bundles
for XML, SSL, RTF, etc), as well as all software installed by the
manufacturer of your distribution.  These files are usually essential 
for having a fully functional system.  Thus, making modifications to 
these files is highly discouraged.  In addition, only the system 
administrator ('root' on most UNIX systems) should have permissions to 
write to that domain.



The Local domain
----------------
While at first glance, the Local domain seems very similar to the 
System domain, there are several differences between them.  The most
important thing is the differing purpose of the Local domain, as it is
meant as the location for installing software which was not included
with your GNUstep distribution.  These may include third party 
applications, custom extension libraries and their related header files,
etc.  Another difference is the possible permission for normal users to
install software in this location without having to ask the system 
administrator for permission to do so.  The Local domain is - as the name 
suggests - usually installed as /Local on your GNUstep system.



The Network domain
------------------
If you are working with a GNUstep system at home, the /Network folder
is probably empty, as it is of small use on stand alone systems.  However,
the Network domain is of great use in networked, corporate environments.
Its main purpose is to hold files exported from a central server in your
network or from other workstations.  Most times, remote directories 
containing applictations or general data used by several workstations 
in the network are mounted using the Network File System (NFS).  Such 
usage gives administrators the possibility of providing application
or resources to a vast number of workstations while only having to 
manage the software in one place.  This is especially useful when
workstations are used by several users with different tasks and requirements.



The User domain
---------------
In current GNUstep versions, the User domain is located in the Users
folder, located in the /Local domain.  On systems where GNUstep is 
installed optionally, the User domain can mostly be found in a 
subdirectory of the user's home directory called 'GNUstep'.  As the name
suggests, the main purpose of the User domain is to hold GNUstep 
related files which shall not be available to other users on the system
but only to the user owning them.  This includes the GNUstep defaults
database, which holds system settings, application preferences and 
customized resources, as well as temporary data related to services 
and file type associations for programs.  In addition to these special 
files, the User domain features the same structure as the other domains.





MODIFICATIONS OVERVIEW
======================

/System

- moved /System/Headers to /System/Library/Headers
- moved /System/Makefiles to /System/Library/Makefiles
- moved /System/Developer/Palettes to /System/Library/Palettes
- moved /System/Libraries/Resources to /System/Library/Resources
- moved /System/Libraries/Resources/DTDs to /System/Library/DTDs
- moved /System/Libraries/Resources/DocTemplates to /System/Library/DocTemplates
- moved /System/Libraries/Resources/Languages to /System/Library/Languages
- moved /System/Libraries/Resources/NSCharacterSets to 
/System/Library/NSCharacterSets
- moved /System/Libraries/Resources/NSTimeZones to /System/Library/NSTimeZones


/Local

- moved /Local/Headers to /Local/Library/Headers
- moved /Local/Developer/Palettes to /Local/Library/Palettes





Proposed GNUstep Filesystem Hierarchy For The "System" Domain 
=============================================================


/System

        /Applications
        /Library
                /Bundles
                        /SSL.bundle
                        /SSL.bundle/Contents
                        /SSL.bundle/Contents/Resources
                        /SSL.bundle/Resources
                /Colors
                /DTDs
                /DocTemplates
                /Frameworks
                /Headers
                        /Foundation
                        /gnustep
                                /base
                                /unicode
                /Languages
                /Libraries
                /Makefiles
                        /Additional
                        /Instance
                                /Shared
                        /Master
                        /ix86
                /NSCharacterSets
                /NSTimeZones
                        /zones
                                /Africa
                                /America
                                        /Indiana
                                        /Kentucky
                                /Antarctica
                                /Arctic
                                /Asia
                                /Atlantic
                                /Australia
                                /Brazil
                                /Canada
                                /Chile
                                /Etc
                                /Europe
                                /Indian
                                /Mexico
                                /Mideast
                                /Pacific
                                /SystemV
                                /US
                /Palettes
                /PostScript
                        /PPDs
                /Services
        /Tools
                        /Java




/System/Library/Resources/English.lproj:
/System/Library/Resources/French.lproj:
/System/Library/Resources/German.lproj:
/System/Library/Resources/Italian.lproj:


(NOTE:  I have no idea what to do with the preceding four lines... I suppose 
they could go into /System/Library/Libraries/Resources.)



Proposed GNUstep Filesystem Hierarchy For The "Local" Domain
============================================================


/Local

        /Applications
        
        /Library
                /Bundles
                /Colors
                /Frameworks
                /Headers
                /Libraries
                /Palettes
                /PostScript
                /Resources
                /Services
        /Tools
                /Java



Proposed GNUstep Filesystem Hierarchy For The "Network" Domain
==============================================================


/Network

        /Applications
        /Servers
        /Users





The /System Domain
==================

The /System directory is the location of gnustep-make, gnustep-base,
gnustep-gui, gnustep-x[gps|dgs], and any accompanying libraries or frameworks
that are distributed as part of the GNUstep Project.  This directory MUST exist
for a proper installation of GNUstep.

Using the --prefix option to the autoconf script in gnustep-make, an
installation of GNUstep may be placed wherever the user wishes.  Common options
are:


        /usr/GNUstep
        /usr/local/GNUstep
        /opt/GNUstep
        /


For the purposes of this document, we will assume that the GNUstep root is /,
meaning that the System directory is installed as /System.



/System/Applications
--------------------

The /System/Applications directory contains applications that are specific to
development with, or the maintenance of, GNUstep.  This option can be
overridden, if the user wishes to install such applications in a local
installation directory.

Applications that may be installed in /System/Applications include:


        Gorm.app
        ProjectCenter.app
        GSDefaults.app
        GWorkspace.app



/System/Library
---------------

The /System/Library directory contains most of the functional code of the
GNUstep Development Environment.  The primary reason for this structure is to
keep a complimentary environment with Mac OS X, the current incarnation of the
OpenStep initiative.  This allows easier cross platform development, by keeping
a standard directory layout, providing developers with a relatively common
hierarchy to work within.



/System/Library/Bundles
-----------------------

The /System/Library/Bundles directory contains application bundles that are
specific to the GNUstep development environment.  All bundles must have the
extension ".bundle", to indicate their usage.

Bundles that may be installed in /System/Library/Bundles include:


        SSL.bundle
        TextConverters.bundle



/System/Library/Colors
----------------------

The /System/Library/Colors directory contains text files that define system
specific color mappings for use within any GNUstep libraries or applications
that require color definitions.



/System/Library/DTDs
--------------------

The /System/Library/DTDs directory contains any Document Type Definitions
required by the GNUstep development environment.  All GNUstep specific DTDs 
must be contained within this directory.

Document Type Definitions that may be installed in /System/Library/DTDs include:


        gsdoc-0_6_5.dtd
        gsdoc-0_6_6.dtd
        gsdoc-0_6_7.dtd
        plist-0_9.dtd
        xhtml-lat1.ent
        xhtml-special.ent
        xhtml-symbol.ent
        xhtml1-frameset.dtd
        xhtml1-strict.dtd
        xhtml1-transitional.dtd



/System/Library/DocTemplates
----------------------------

The /System/Library/DocTemplates directory contains text templates for automatic
documentation, as generated by gsdoc, or it's equivalent, autodoc.  Any
additional documentation template types must be placed in this directory, as a
central location for documentation template types.  Any templates installed
within this directory must have an extension indicating what type of
documentation system it is referenced by (ie. .gsdoc for the GNUstep
implementation of autodoc).

Templates that may be installed in /System/Library/DocTemplates include:


        AutoDocTemplate.gsdoc
        indextemplate.gsdoc



/System/Library/Frameworks
--------------------------

The /System/Library/Frameworks directory contains GNUstep specific frameworks,
required by the system, or system applications.

Frameworks are a type of bundle, which include, within their directory
structure, a shared library providing a specific functionality (or group of
related functionalities), and all resources required by that shared library.

Frameworks that are located within /System/Library/Frameworks are specific to
GNUstep, or applications required by GNUstep.  Any other frameworks, such as
ones installed by applications compiled by the user, should reside within a
different structure (see: /Local/Library/Frameworks).

All frameworks must have the extension ".framework", to indicate their usage.

Frameworks that may be installed in /System/Library/Frameworks include:


        GSWExtensions.framework
        GSWExtensionsGSW.framework
        GSWeb.framework


(NOTE:  Optimally, all GNUstep core libraries would reside in this structure, as
well, as frameworks.  This has not been discussed, and as such, I shall not 
include any reference to their placement.)



/System/Library/Headers
-----------------------

The /System/Library/Headers directory contains Objective-C header files required
by the GNUstep development environment for compilation.  A user should NEVER
modify any of the headers located within this directory.



/System/Library/Languages
-------------------------

The /System/Library/Languages directory contains files which specify formats 
for country-specific displays of data, such as dates, times, currencies, etc.
These files are stored as plain ASCII text, and as the name of the language or
nationality.  Also contained herein is a file which maps the ISO
internationalisation language codes to the GNUstep language file that defines
it.

Language files that may be installed in /System/Library/Languages include:


        Dutch
        English
        French
        German
        Italian
        Locale.aliases



/System/Library/Libraries
-------------------------

The /System/Library/Libraries directory contains the primary GNUstep libraries
available to the system.

Libraries that may be installed in /System/Library/Libraries include:


        libgnustep-base.so.*
        libgnustep-gui.so.*

(NOTE:  The Libraries directory being in Library may sound somewhat redundant,
however, it could be read as "a System Library of shared libraries".)



/System/Library/Makefiles
-------------------------

The /System/Library/Makefiles directory contains the different types of
makefiles used by the GNUstep development environment to build GNUstep
Objective-C applications.  These makefiles are included by a GNUmakefile, which
is used to build a project under the GNUstep development environment.



/System/Library/NSCharacterSets
-------------------------------

The /System/Library/NSCharacterSets directory contains data files that provide
the bitmapped descriptions of how to display Unicode character sets, as
specified by the Unicode Consortium.  All files within the NSCharacterSets
directory must have an extension of ".charset".

Character sets that may be installed in /System/Library/NSCharacterSets include:

        alphanumericCharSet.dat
        controlCharSet.dat
        decimalDigitCharSet.dat
        decomposableCharSet.dat
        illegalCharSet.dat
        letterCharSet.dat
        lowercaseLetterCharSet.dat
        nonBaseCharSet.dat
        punctuationCharSet.dat
        symbolAndOperatorCharSet.dat
        uppercaseLetterCharSet.dat
        whitespaceAndNlCharSet.dat
        whitespaceCharSet.dat



/System/Library/NSTimeZones
---------------------------

The /System/Library/NSTimeZones directory contains the timezone information
files required by the GNUstep development environment to set a local machine's
timezone.  The main NSTimeZones directory consists of several general zones 
(referenced primary by their offset from GMT), and subdirectories for 
individual nations or geographical areas, each containing timezone information 
files for regions within those nations or geographical areas.



/System/Library/Palettes
------------------------

The /System/Library/Palettes directory contains additional development palettes
for Gorm, the GNUstep Interface Builder clone.



/System/Library/PostScript
--------------------------

The /System/Library/PostScript directory contains directories for specific 
PostScript document types and definitions, allowing applications written using 
the GNUstep development environment to display PostScript documents, or 
communicate with printers using PostScript.



/System/Library/Services
------------------------

The /System/Library/Services directory contains bundles that are specifically
built to provide functionality between different programs (for example, spell
checking, creation of a note from text within an email application).  Services 
that are installed on the system must an extension of ".service".

Services that may be installed in /System/Library/Services include:


        example.service
        GSspell.service



/System/Tools
-------------

The /System/Tools directory contains executable programs and scripts, 
used to manipulate documentation, application bundles, distributed objects, 
and the defaults database.

Tools that may be installed in /System/Tools include:


        HTMLLinker
        Java
        autogsdoc
        debugapp
        defaults
        font_cacher
        gdnc
        gdomap
        gopen
        gpbs
        gsdoc
        make_services
        openapp
        opentool
        pl2link
        pldes
        plmerge
        plparse
        plser
        set_show_service
        sfparse






The /Local Domain
=================

The /Local domain is the location of libraries, frameworks, bundles, and 
supporting files for locally installed applications or tools that are not
distributed as part of the GNUstep Project.  This directory MUST exist
for a proper installation of GNUstep.



/Local/Applications
-------------------

The /Local/Applications directory contains applications that are installed by
the individual user, and are not a part of the GNUstep Project.  This option 
can be overridden, if the user wishes to install such applications in a local
installation directory, such as their home directory.

Applications that may be installed in /Local/Applications include:


        GNUMail.app
        LuserNET.app
        CDPlayer.app
        HostAddress.app
        CodeEditor.app



/Local/Library
--------------

The /Local/Library directory contains most of the functional code for 
application support relating to user installed applications.

The primary reason for this structure is to keep a complimentary structure 
with the GNUstep System Domain.  This allows easier development, by keeping a
standard directory layout, providing developers with a relatively common
hierarchy to work within.



/Local/Library/Bundles
----------------------

The /Local/Library/Bundles directory contains application bundles that are
specific to locally installed applications.  All bundles must have the
extension ".bundle", to indicate their usage.  As an option, an application
installing bundles could create a directory within /Local/Library/Bundles
specifically for their own use (for example:
/Local/Library/Bundles/MyProg/AddedFunctionality.bundle)

Bundles that may be installed in /Local/Library/Bundles include:


        CodeEditorBundle.bundle
        TCPSSLConnection.bundle
        


/Local/Library/Colors
---------------------

The /Local/Library/Colors directory contains text files that define system
specific color mappings for use within any application libraries or locally
installed applications that require additional color definitions, beyond those
installed by default by GNUstep.



/Local/Library/Frameworks
-------------------------

The /Local/Library/Frameworks directory contains application specific
frameworks required by user installed applications, or installed for local 
development.

Frameworks are a type of bundle, which include, within their directory
structure, a shared library providing a specific functionality (or group of
related functionalities), and all resources required by that shared library.

Frameworks that are located within /Local/Library/Frameworks are specific to
applications required by GNUstep.  

All frameworks must have the extension ".framework", to indicate their usage.

Frameworks that may be installed in /System/Library/Frameworks include:


        GNUMail.framework
        


/Local/Library/Headers
----------------------

The /Local/Library/Headers directory contains Objective-C header files
that are provided by locally installed applications.  An application should
create it's own directory within /Local/Library/Headers to contain headers
specific to it's own use.



/Local/Library/Libraries
------------------------

The /Local/Library/Libraries directory contains the shared libraries
for locally installed applications.

Libraries that may be installed in /Local/Library/Libraries include:


        libGNUMail.so.*
        libPantomime.so.*
        libgnustep-db.so.*
        

(NOTE:  The Libraries directory being in Library may sound somewhat redundant,
however, it could be read as "a Local Library of shared libraries".)



/Local/Library/Palettes
-----------------------

The /Local/Library/Palettes directory contains additional development palettes
for Gorm, the GNUstep Interface Builder clone.



/Local/Library/PostScript
-------------------------

The /Local/Library/PostScript directory contains directories for locally
installed specific PostScript document types and definitions, allowing
applications written using the GNUstep development environment to display
PostScript documents, or communicate with printers using PostScript.



/Local/Library/Services
-----------------------

The /Local/Library/Services directory contains bundles that are specifically
built to provide functionality between different programs (for example, spell
checking, creation of a note from text within an email application).  Services 
that are installed on the system must an extension of ".service".

Services that may be installed in /Local/Library/Services include:


        MyProgSpecial.service (an example service)



/Local/Tools
------------

The /Local/Tools directory contains executable programs and scripts, 
used to manipulate documentation, application bundles, distributed objects, 
and the defaults database.

Tools that are written in languages other than Objective-C, or are developed
to work with other runtime environments may have their own directory within
the /Local/Tools directory (for example:  /Local/Tools/Java).



/Local/Library/Resources
------------------------

(I'm not sure what to put for this. :/  Nothing on my system uses it.)






The /Network Domain
===================

The /Network Domain is the location for all exported applications, remotely
mounted filesystems, and remote home directories for users made available via
directory services.



/Network/Applications
---------------------

The /Network/Applications directory contains locally installed applications 
that are to be made available via the network to other computers.



/Network/Servers
----------------

The /Network/Servers directory contains the mount points for remotely mounted
filesystems.  If you wish to mount the /Network/Applications directory from
MachineA, and you are using MachineB, you would mount
MachineA:/Network/Applications on /Network/Servers/MachineA on MachineB.



/Network/Users
--------------

The /Network/Users directory contains user home directories that have been
remotely mounted on the local computer.