GNUstep.org
[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

1.4 Structure of a Domain

In this section we examine the interesting locations in a domain. We will enumerate the locations, and discuss what should be installed in each location, and how they are mapped to directories on disk in the GNUstep filesystem layout and in a general filesystem layout.

1.4.1 The GNUstep Filesystem Layout  
1.4.2 Accessing Domain Locations  
1.4.3 Applications  
1.4.4 Admin Applications  
1.4.5 Web Applications  
1.4.6 Tools  
1.4.7 Admin Tools  
1.4.8 Library  
1.4.9 Headers  
1.4.10 Libraries  
1.4.11 Documentation  
1.4.12 Documentation (Info)  
1.4.13 Documentation (Man Pages)  
1.4.14 Folders inside Library  


1.4.1 The GNUstep Filesystem Layout

We quickly present the GNUstep filesystem layout for a domain first because it is an essential reference for all discussions on the structure of a domain.

The GNUstep filesystem layout is the simplest layout, in which every domain is a directory on disk, and all locations in the domain are subdirectories of the domain.

In that case, a domain has the following structure on disk:
 
 Domain/
        Applications/
        Applications/Admin/
        Defaults/   (User domain only)
        Library/
        Library/ApplicationSupport/
        Library/ApplicationSupport/Palettes
        Library/Bundles/
        Library/Documentation/
        Library/Documentation/info/
        Library/Documentation/man/
        Library/Frameworks/
        Library/Headers/
        Library/Libraries/
        Library/Libraries/Java/
        Library/Libraries/Resources/
        Library/Makefiles/   (System domain only)
        Library/Services/
        Library/Tools/Resources/
        Library/WebApplications/
        Tools/
        Tools/Admin/

The terminology for locations is derived from this filesystem layout, and it can be useful to use this directory structure as a reference point for all discussions. For example, every domain must have a 'Library' location.


1.4.2 Accessing Domain Locations

In order to install and run software that uses some resources, you need to be able to install the resources in the appropriate location, and your software needs to be able to locate these resources when it's running.

Since domain locations can be mapped to arbitrary locations on disk, you must use the appropriate gnustep-make and gnustep-base facilities to install things in the right place and to find things at runtime.

GNUstep-make creates makefile variables for all the domain locations. If you need to perform some custom installation for your software, you must use these variables to make sure your installation will work with all filesystem layouts. For example, the `Applications' location for the domain where the software will be installed is available as the GNUSTEP_APPS variable. You can also access the locations for specific domains by using the variables GNUSTEP_SYSTEM_APPS, GNUSTEP_NETWORK_APPS, GNUSTEP_LOCAL_APPS and GNUSTEP_USER_APPS.

GNUstep-base provides you with the NSSearchPathForDirectoriesInDomains() function that allows you to retrieve the domain locations at runtime. You must lookup resources only via this function. For example, the `Applications' location can be found by using the NSApplicationDirectory directory key, so you can use it in your software to iterate over all the `Applications' directories in the various domains searching for an application.

In general, all interesting domain locations have a set of variables defined in gnustep-make (such as GNUSTEP_APPS, GNUSTEP_SYSTEM_APPS, GNUSTEP_NETWORK_APPS, GNUSTEP_LOCAL_APPS and GNUSTEP_USER_APPS) and a corresponding directory key in gnustep-base (such as NSApplicationDirectory).

When examining the various domain locations, we will explicitly mention the gnustep-make variables and the gnustep-base directory keys that can be used to access them.


1.4.3 Applications

The `Applications' location contains applications. Applications are programs that typically have a GUI interface and contain associated resource files, such as images, localization files and other program elements.

Important applications which are part of GNUstep and which are often distributed as part of a core GNUstep distribution include:
 
Gorm.app
ProjectCenter.app
GWorkspace.app
Preferences.app

In GNUmakefiles, the `Applications' location is available via the GNUSTEP_APPS variable, which is the Applications location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_APPS, GNUSTEP_NETWORK_APPS, GNUSTEP_LOCAL_APPS and GNUSTEP_USER_APPS.

In gnustep-base, the `Applications' locations are available by using the NSApplicationDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.4 Admin Applications

The `Admin Applications' location contains applications that are only useful to the system administrator. A normal user wouldn't have enough privileges to use these applications in a useful way.

In GNUmakefiles, the `Admin Applications' location is available via the GNUSTEP_ADMIN_APPS variable, which is the Admin Applications location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_ADMIN_APPS, GNUSTEP_NETWORK_ADMIN_APPS, GNUSTEP_LOCAL_ADMIN_APPS and GNUSTEP_USER_ADMIN_APPS.

In gnustep-base, the `Admin Applications' locations are available by using the NSAdminApplicationDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.5 Web Applications

The `Web Applications' location contains web applications that were created using GSWeb or SOPE. These are programs contained with their resources in small wrappers very similar to standard applications.

In GNUmakefiles, the `Web Applications' location is available via the GNUSTEP_WEB_APPS variable, which is the Web Applications location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_WEB_APPS, GNUSTEP_NETWORK_WEB_APPS, GNUSTEP_LOCAL_WEB_APPS and GNUSTEP_USER_WEB_APPS.

In gnustep-base, the `Web Applications' locations are available by using the GSWebApplicationDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.6 Tools

The `Tools' location contains tools and executable scripts. Tools are programs which generally have a command-line interface. Most are not meant to be used by the average user.

Important tools which are part of GNUstep and which are often distributed as part of a core GNUstep distribution include:
 
openapp
defaults
gdomap
gdnc
gpbs

In GNUmakefiles, the `Tools' location is available via the GNUSTEP_TOOLS variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_TOOLS, GNUSTEP_NETWORK_TOOLS, GNUSTEP_LOCAL_TOOLS and GNUSTEP_USER_TOOLS.

In gnustep-base, the `Tools' locations are available by using the GSToolsDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.7 Admin Tools

The `Admin Tools' location contains tools and executable scripts that are only useful to the system administrator. A normal user wouldn't have enough privileges to use these applications in a useful way.

In GNUmakefiles, the `Admin Tools' location is available via the GNUSTEP_ADMIN_TOOLS variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_ADMIN_TOOLS, GNUSTEP_NETWORK_ADMIN_TOOLS, GNUSTEP_LOCAL_ADMIN_TOOLS and GNUSTEP_USER_ADMIN_TOOLS.

In gnustep-base, the `Admin Tools' locations are available by using the GSAdminToolsDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.8 Library

The `Library' location contains most of the resources that are located and loaded at runtime. These resources are organized in folders (directories) inside `Library'; the most important `Library' folders will be described later on.

Like all systems inspired by OpenStep, resources are mostly organized in bundles and small wrappers that contain both machine-dependent files (such as executables or loadable object files) and general machine-independent resources (such as images or text files). For this reason, the `Library' location will contain both machine-dependent and machine-independent files.

The structure of the folders within Library is the same in all filesystem layouts, with a few exceptions: in the GNUstep filesystem layout, the Libraries, Headers, Documentation and WebApplications folders are all inside Library, but this is not necessarily true for other filesystem layouts.

Vice versa, it's common on other filesystem layouts (eg, FHS) to put Applications and Admin Applications as folders inside Library.

In GNUmakefiles, the `Library' location is available via the GNUSTEP_LIBRARY variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_LIBRARY, GNUSTEP_NETWORK_LIBRARY, GNUSTEP_LOCAL_LIBRARY and GNUSTEP_USER_LIBRARY.

In gnustep-base, the `Library' locations are available by using the NSLibraryDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.9 Headers

The Headers location contains header files associated with a library located in Libraries.

In GNUmakefiles, the `Headers' location is available via the GNUSTEP_HEADERS variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_HEADERS, GNUSTEP_NETWORK_HEADERS, GNUSTEP_LOCAL_HEADERS and GNUSTEP_USER_HEADERS.

In gnustep-base, the `Headers' location is not currently available.


1.4.10 Libraries

The Libraries location contains libraries (shared/static object files that are linked into programs). (NOTE: In the GNUstep filesystem layout, the Libraries directory being in Library may sound somewhat redundant, however, it could be read as "a Library of shared libraries").

In the GNUstep filesystem layout, the Library/Libraries folder contains two other folders: Resources and Java. It's important to notice that when the Libraries location is moved elsewhere, these folders are not moved; they will still be in Library/Libraries/Resources and Library/Libraries/Java.

In GNUmakefiles, the `Libraries' location is available via the GNUSTEP_LIBRARIES variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_LIBRARIES, GNUSTEP_NETWORK_LIBRARIES, GNUSTEP_LOCAL_LIBRARIES and GNUSTEP_USER_LIBRARIES.

In gnustep-base, the `Libraries' locations are available by using the GSLibrariesDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.11 Documentation

The Documentation location contains documentation for libraries, applications, etc.

In GNUmakefiles, the `Documentation' location is available via the GNUSTEP_DOC variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_DOC, GNUSTEP_NETWORK_DOC, GNUSTEP_LOCAL_DOC and GNUSTEP_USER_DOC.

In gnustep-base, the `Documentation' locations are available by using the NSDocumentationDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.12 Documentation (Info)

The Documentation (Info) location contains documentation in info format.

In GNUmakefiles, the `Documentation (Info)' location is available via the GNUSTEP_DOC_INFO variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_DOC_INFO, GNUSTEP_NETWORK_DOC_INFO, GNUSTEP_LOCAL_DOC_INFO and GNUSTEP_USER_DOC_INFO.

In gnustep-base, the `Documentation (Info)' locations are not currently available.


1.4.13 Documentation (Man Pages)

The Documentation (Man Pages) location contains Unix man pages.

In GNUmakefiles, the `Documentation (Man Pages)' location is available via the GNUSTEP_DOC_MAN variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_DOC_MAN, GNUSTEP_NETWORK_DOC_MAN, GNUSTEP_LOCAL_DOC_MAN and GNUSTEP_USER_DOC_MAN.

In gnustep-base, the `Documentation (Man)' locations are not currently available.


1.4.14 Folders inside Library

In this section we discuss the standard folders that are available inside the Library location. To find any of these folders, just find the location of Library and then append the folder name (for example, in a GNUmakefile you can access the 'ColorPickers' folder of the installation domain as $GNUSTEP_LIBRARY/ColorPickers).

Some of the folders can also be accessed using direct variables, such as GNUSTEP_BUNDLES. You should prefer using these direct variables if you can because they are more future-proof (in case some of the folders become independent from Library in the future). All such cases should be documented here.

1.4.14.1 ApplicationSupport  
1.4.14.2 Bundles  
1.4.14.3 ColorPickers  
1.4.14.4 Colors  
1.4.14.5 DTDs  
1.4.14.6 DocTemplates  
1.4.14.7 Fonts  
1.4.14.8 Frameworks  
1.4.14.9 Images  
1.4.14.10 Libraries/Java  
1.4.14.11 Libraries/Resources  
1.4.14.12 KeyBindings  
1.4.14.13 PostScript  
1.4.14.14 Services  
1.4.14.15 Sounds  
1.4.14.16 Tools/Resources  


1.4.14.1 ApplicationSupport

This directory contains bundles and other resources that are provided for an application, but that are not specifically distributed with that application. For instance, these may be third-party resources for an application.

For example, modules for the Preferences application may be stored here, in a `Preferences' subdirectory. In particular, Palettes for Gorm are stored in `ApplicationSupport/Palettes'.

In GNUmakefiles, this location is available via the GNUSTEP_APPLICATION_SUPPORT variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_APPLICATION_SUPPORT, GNUSTEP_NETWORK_APPLICATION_SUPPORT, GNUSTEP_LOCAL_APPLICATION_SUPPORT and GNUSTEP_USER_APPLICATION_SUPPORT.

In gnustep-base, the ApplicationSupport locations are available by using the NSApplicationSupportDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.14.2 Bundles

This directory contains bundles. Bundles are collections of executable code and associated resources that may be loaded at runtime by an application or tool. Note: this directory is depreciated. Use ApplicationSupport to install bundles that can be used by an application.

In GNUmakefiles, this location is available via the GNUSTEP_BUNDLES variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_BUNDLES, GNUSTEP_NETWORK_BUNDLES, GNUSTEP_LOCAL_BUNDLES and GNUSTEP_USER_BUNDLES.

In gnustep-base, you can access the Bundles location as a folder inside the Library location.


1.4.14.3 ColorPickers

This directory contains bundles that are used by the color picking system. They may include code that implements picking colors from a color wheel, a custom defined list of colors, etc.

This folder is accessed as the ColorPickers folder inside Library.


1.4.14.4 Colors

This directory contains files that define specific color mappings for use within libraries or applications that require color definitions.

This folder is accessed as the Colors folder inside Library.


1.4.14.5 DTDs

This directory contains any Document Type Definitions required for document parsing.

This folder is accessed as the DTDs folder inside Library.


1.4.14.6 DocTemplates

This directory contains text templates for automatic documentation, as generated by 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).

This folder is accessed as the DocTemplates folder inside Library.


1.4.14.7 Fonts

This directory contains fonts and files for organizing font information.

This folder is accessed as the Fonts folder inside Library.


1.4.14.8 Frameworks

This directory contains frameworks. 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.

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

Use of frameworks is generally discouraged, as it is difficult to support them in a clean way on multiple platforms. Bundles are a better method of organizing shared collections of resources and code.

In GNUmakefiles, this location is available via the GNUSTEP_FRAMEWORKS variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_FRAMEWORKS, GNUSTEP_NETWORK_FRAMEWORKS, GNUSTEP_LOCAL_FRAMEWORKS and GNUSTEP_USER_FRAMEWORKS.

In gnustep-base, the Frameworks locations are available by using the GSFrameworksDirectory directory key for NSSearchPathForDirectoriesInDomains().


1.4.14.9 Images


1.4.14.10 Libraries/Java

This directory contains Java classes. If you are using Java with GNUstep, you probably want to make sure these directories are in your CLASSPATH.

In GNUmakefiles, this location is available via the GNUSTEP_JAVA variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_JAVA, GNUSTEP_NETWORK_JAVA, GNUSTEP_LOCAL_JAVA and GNUSTEP_USER_JAVA.

In gnustep-base, you can access the Libraries/Java location as the Libraries/Java folder inside the Library location.


1.4.14.11 Libraries/Resources

This directory contains resources used by shared libraries. In GNUstep a shared library can have an associated resource bundle (a bundle only composed of resources, with no object file), which is then installed into this directory.

For example, gnustep-base will get its resource bundle installed into GNUSTEP_SYSTEM_LIBRARY/Libraries/Resources/gnustep-base.

In GNUmakefiles, this location is available via the GNUSTEP_RESOURCES variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_RESOURCES, GNUSTEP_NETWORK_RESOURCES, GNUSTEP_LOCAL_RESOURCES and GNUSTEP_USER_RESOURCES.

In gnustep-base, you can access the resource bundle associated with a library by using the [NSBundle +bundleForLibrary:] method (it is a GNUstep extension).


1.4.14.12 KeyBindings


1.4.14.13 PostScript

This 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.

This folder is accessed as the PostScript folder inside Library.


1.4.14.14 Services

This 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".

In GNUmakefiles, this location is available via the GNUSTEP_SERVICES variable, which is the location for the domain in which the software will be installed. You can also reference the locations in the various domains directly by using the variables GNUSTEP_SYSTEM_SERVICES, GNUSTEP_NETWORK_SERVICES, GNUSTEP_LOCAL_SERVICES and GNUSTEP_USER_SERVICES.

In gnustep-base, you can access the Services location as a folder inside the Library location.


1.4.14.15 Sounds

This directory contains sound files.


1.4.14.16 Tools/Resources

This directory contains resources used by tools. In GNUstep a tool can have an associated resource bundle (a bundle only composed of resources, with no object file), which is then installed into this directory.

For example, a tool called myTool will get its resource bundle installed into GNUSTEP_SYSTEM_LIBRARY/Tools/Resources/myTool.

In GNUmakefiles, this location is available as the `Tools/Resources' folder inside the Library location.

In gnustep-base, you can access the resource bundle associated with your tool by using the [NSBundle +mainBundle] method (this semantic is a GNUstep extension).


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by Adam Fedor on January, 1 2008 using texi2html