1
\input texinfo @c -*-texinfo-*-
2
@c GNUstep filesystem hierarchy
4
@setfilename filesystem.info
5
@settitle GNUstep Filesystem Hierarchy Document
7
@setcontentsaftertitlepage
11
@title GNUstep Filesystem Hierarchy Document
13
@vskip 0pt plus 1filll
18
@vskip 0pt plus 1filll
19
Authors: Tim Harrison, Martin Brecher, Adam Fedor, Nicola Pero
21
Permission is granted to copy, distribute and/or modify this document
22
under the terms of the GNU Free Documentation License, Version 1.1 or
23
any later version published by the Free Software Foundation.
27
@node Top, The System Domain, (dir), (dir)
28
@top GNUstep Filesystem Hierarchy
33
* The Network Domain::
39
On GNUstep, there are four separate places where files related to GNUstep
40
are installed: these places are called "domains". These four
41
domains are the System domain, the Local domain, the Network domain,
42
and the User domain. Each of these domains serve a special purpose.
44
The following is a general overview of the GNUstep domains. A detailed
45
explanation of the directory structure contained within each domain is
46
found later in this document.
49
@node The System Domain, The Local Domain, Top, Top
50
@section The System Domain
52
The System domain is found in the @file{System} folder of the GNUstep
53
installation. This directory contains all files which were included
54
in the default GNUstep installation or distribution. Normally these
55
include the basic GNUstep libraries (Foundation and AppKit), and might
56
include essential system applications (the Workspace Manager, the
57
Editor, applications related to system administrative tasks), the
58
developer applications (Project Center and Gorm, as well as header
59
files), essential extensions (bundles for XML, SSL, RTF, etc), as well
60
as all software installed by the manufacturer of your distribution.
61
These files are usually essential for having a fully functional
62
system. Thus, making modifications to these files is highly
63
discouraged. In addition, only the system administrator ('root' on
64
most UNIX systems) should have permissions to write to that domain.
68
@node The Local Domain, The Network Domain, The System Domain, Top
69
@section The Local Domain
71
While at first glance, the Local domain seems very similar to the
72
System domain, there are several differences between them. The most
73
important thing is the differing purpose of the Local domain, as it is
74
meant as the location for installing software which was not included
75
with your GNUstep distribution and which you or your local sysadmin
76
compile and/or install manually. These may include third party
77
applications, custom extension libraries and their related header
78
files, etc. The Local domain is - as the name suggests - usually
79
installed as @file{Local} on your GNUstep system. Every software
80
(except for gnustep-make, gnustep-base, gnustep-gui and gnustep-back
81
which by default install into the System domain) should install by
82
default into the Local domain, so that if you download a source
83
tarball of the software and you install it, it installs by default in
84
the right place for this operation (the Local domain). Distributions
85
should override this default manually when they package the software
86
they want to distribute as part of their distribution, so that in that
87
case the software is installed in the System domain.
90
@node The Network Domain, The Users Domain, The Local Domain, Top
91
@section The Network Domain
93
The @file{Network} domain is optional and is currently coalesced with
94
the @file{Local} domain by default; this is particularly appropriate
95
for use on stand alone systems such as your home workstation.
96
However, the Network domain can be of great use in networked,
97
corporate environments. Its main purpose is to hold files exported
98
from a central server in your network or from other workstations.
99
Most times, remote directories containing applictations or general
100
data used by several workstations in the network are mounted using the
101
Network File System (NFS). Such usage gives administrators the
102
possibility of providing application or resources to a vast number of
103
workstations while only having to manage the software in one place.
104
This is especially useful when workstations are used by several users
105
with different tasks and requirements. If you want to take advantage
106
of the @file{Network} domain, you need to enable it when you configure
111
@node The Users Domain, Hierarchy, The Network Domain, Top
112
@section The Users Domain
114
On systems where GNUstep is installed optionally, the Users domain can
115
usually be found in a subdirectory of the user's home directory called
116
'GNUstep'. This location is configurable, and some installations may
117
put this directly in the user's directory (and typical user's home
118
directories would be located in a @file{Users} folder). As the name
119
suggests, the main purpose of the Users domain is to hold GNUstep
120
related files which shall not be available to other users on the
121
system but only to the user owning them. This includes the GNUstep
122
defaults database, which holds system settings, application
123
preferences and customized resources, as well as temporary data
124
related to services and file type associations for programs. It also
125
holds user installed applications and tools (each user has the ability
126
to install their own version of an application or tool). In
127
addition to these special files, the User domain features the same
128
structure as the other domains.
133
@node Hierarchy, Description, The Users Domain, Top
139
* Network Hierarchy::
144
@node System Hierarchy, Local Hierarchy, Hierarchy, Hierarchy
155
@node Local Hierarchy, Network Hierarchy, System Hierarchy, Hierarchy
165
@node Network Hierarchy, User Hierarchy, Local Hierarchy, Hierarchy
175
@node User Hierarchy, Library Folder, Network Hierarchy, Hierarchy
179
@emph{User's GNUstep root dir}/
185
@node Library Folder, , User Hierarchy, Hierarchy
186
@subsection Library Folder
188
@multitable @columnfractions 0.2 0.2 0.2 0.2 0.2
189
@item ApplicationSupport
193
@item Defaults @tab @tab @tab @tab @emph{user only}
204
@item @tab @tab gnustep-base @tab @tab @emph{system only}
205
@item @tab @tab @tab .lproj folders
206
@item @tab @tab @tab CharacterSets
207
@item @tab @tab @tab TimeZones
208
@item @tab @tab @tab Languages
209
@item @tab @tab gnustep-gui @tab @tab @emph{system only}
210
@item @tab @tab @tab .lproj folders
211
@item @tab @tab @tab TextConverters
212
@item Makefiles @tab @tab @tab @tab @emph{system only}
213
@item @tab Additional
221
@node Description, , Hierarchy, Top
225
* System Description::
226
* Local Description::
227
* Network Description::
234
@node System Description, Local Description, Description, Description
237
The System directory is the location of the GNUstep makefile package,
238
base, gui and backend libraries, and any accompanying software that is
239
distributed as part of whatever distribution of GNUstep you are using.
240
This directory MUST exist for a proper installation of GNUstep.
242
Using the --prefix option to the configure script in gnustep-make, an
243
installation of GNUstep may be placed wherever the installer wishes;
244
the System, Local (and optionally Network) domain by default will be
245
subdirectory of this root location.
256
All directories referenced in this document are relative to this root location.
258
@node Local Description, Network Description, System Description, Description
261
The Local domain is the location of libraries, frameworks, bundles,
262
and supporting files for locally installed applications or tools that
263
are not distributed as part of the distribution that you are using,
264
but that are compiled and/or installed manually by you or your
265
sysadmin. This directory MUST exist for a proper installation of
268
@node Network Description, Applications, Local Description, Description
271
The Network Domain is the location for all exported applications, remotely
272
mounted filesystems, and remote home directories for users made available via
273
directory services. It is optional, and disabled by default.
275
@node Applications, Tools, Network Description, Description
276
@subsection Applications
278
The @file{Applications} directory contains applications. Applications
279
are programs that typically have a GUI interface and contain associated
280
resource files, such as images, localization files and other program
283
Important applications which are part of GNUstep and which are often
284
distributed as part of a core GNUstep distribution (and so installed
285
in the @file{System/Applications} folder) include:
294
@node Tools, share, Applications, Description
297
The @file{Tools} directory contains tools and executable
298
scripts. Tools are programs which generally have a command-line
299
interface. Most are not meant to be used by the average user.
301
Tools that are written in languages other than Objective-C, or are developed
302
to work with other runtime environments may have their own directory within
303
the Tools directory (for example: @file{Tools/Java}).
305
@node share, Library, Tools, Description
308
The share directory is used for configuration and installation
309
of the core GNUstep libraries and any additional libraries that
310
need configuration information. It is used by the configure (autoconf)
314
@node Library, , share, Description
317
The @file{Library} directory contains most of the functional
318
code of the GNUstep Development Environment.
320
The primary reason for the structure of folders within Library is to
321
keep a complimentary structure throughout all domains. This allows
322
easier development, by keeping a standard directory layout, providing
323
developers with a relatively common hierarchy to work within.
326
* ApplicationSupport::
346
@node ApplicationSupport, Bundles, Library, Library
347
@subsubsection ApplicationSupport
349
This directory contains bundles and other resources that are provided
350
for an application, but that are not specifically distributed with that
351
application. For instance, these may be third-party resources for
354
For example, modules for the Preferences application may be stored here,
355
in a @file{Preferences} subdirectory.
357
@node Bundles, ColorPickers, ApplicationSupport, Library
358
@subsubsection Bundles
360
This directory contains bundles. Bundles are collections of executable
361
code and associated resources that may be loaded at runtime by an
362
application or tool. Note: this directory is depreciated. Use
363
ApplicationSupport to install bundles that can be used by an
366
@node ColorPickers, Colors, Bundles, Library
367
@subsubsection ColorPickers
369
This directory contains bundles that are used by the color picking
370
system. They may include code that implements picking colors from a color
371
wheel, a custom defined list of colors, etc.
373
@node Colors, Defaults, ColorPickers, Library
374
@subsubsection Colors
376
This directory contains files that define
377
specific color mappings for use within libraries or applications
378
that require color definitions.
380
@node Defaults, DTDs, Colors, Library
381
@subsubsection Defaults
383
This directory contains files that store defaults for applications, e.g.
384
user preferences. This directory only exists in the User domain.
386
@node DTDs, DocTemplates, Defaults, Library
389
This directory contains any Document Type Definitions
390
required for document parsing.
392
@node DocTemplates, Documenation, DTDs, Library
393
@subsubsection DocTemplates
395
This directory contains text templates for automatic documentation, as
396
generated by autodoc. Any additional documentation template types
397
must be placed in this directory, as a central location for
398
documentation template types. Any templates installed within this
399
directory must have an extension indicating what type of documentation
400
system it is referenced by (ie. .gsdoc for the GNUstep implementation
403
@node Documenation, Fonts, DocTemplates, Library
404
@subsubsection Documentation
406
This directory contains documentation for libraries, applications, etc.
408
@node Fonts, Frameworks, Documenation, Library
411
This directory contains fonts and files for organizing font information.
413
@node Frameworks, Headers, Fonts, Library
414
@subsubsection Frameworks
416
This directory contains frameworks. Frameworks are a type of bundle,
417
which include, within their directory structure, a shared library
418
providing a specific functionality (or group of related
419
functionalities), and all resources required by that shared library.
421
All frameworks must have the extension @file{framework}, to indicate
424
Use of frameworks is generally discouraged, as it is difficult to
425
support them in a clean way on multiple platforms. Bundles are a
426
better method of organizing shared collections of resources and code.
428
@node Headers, Images, Frameworks, Library
429
@subsubsection Headers
431
This directory contains header files associated with a library located
432
in the Libraries directory.
434
@node Images, KeyBindings, Headers, Library
435
@subsubsection Images
437
@node KeyBindings, Libraries, Images, Library
438
@subsubsection KeyBindings
440
@node Libraries, Makefiles, KeyBindings, Library
441
@subsubsection Libraries
443
This directory contains libraries. (NOTE: The Libraries directory
444
being in Library may sound somewhat redundant, however, it could be
445
read as "a Library of shared libraries".)
447
@node Makefiles, PostScript, Libraries, Library
448
@subsubsection Makefiles
450
This directory contains the different types of makefiles used by the
451
GNUstep development environment to build applications, libraries,
452
bundles, etc. These makefiles are usually included in a project
453
specific GNUmakefile, which is used to build a project under the
454
GNUstep development environment.
456
This directory only exists in the System domain.
458
@node PostScript, Services, Makefiles, Library
459
@subsubsection PostScript
461
This directory contains directories for specific
462
PostScript document types and definitions, allowing applications written using
463
the GNUstep development environment to display PostScript documents, or
464
communicate with printers using PostScript.
466
@node Services, Sounds, PostScript, Library
467
@subsubsection Services
469
This directory contains bundles that are specifically
470
built to provide functionality between different programs (for example, spell
471
checking, creation of a note from text within an email application). Services
472
that are installed on the system must an extension of ".service".
474
@node Sounds, , Services, Library
475
@subsubsection Sounds
477
This directory contains sound files.
added
removed
gnustep-make/Documentation/filesystem.texi
