1\input texinfo @c -*-texinfo-*- 2@c GNUstep filesystem hierarchy 3@c %**start of header 4@settitle GNUstep Filesystem Hierarchy Document 5@c %**end of header 6@smallbook 7 8@titlepage 9@title GNUstep Filesystem Hierarchy Document 10 11@vskip 0pt plus 1filll 12 13Last Update: @today{} 14 15@page 16@vskip 0pt plus 1filll 17Authors: Nicola Pero, Tim Harrison, Martin Brecher, Adam Fedor, 18Richard Frith-Macdonald 19 20Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.1 or 22any later version published by the Free Software Foundation. 23 24@end titlepage 25 26@contents 27 28 29@node Top, The System Domain, (dir), (dir) 30@chapter GNUstep Filesystem Hierarchy 31 32@menu 33* The System Domain:: 34* The Local Domain:: 35* The Network Domain:: 36* The Users Domain:: 37* Structure of a Domain:: 38* Configuration:: 39@end menu 40 41On GNUstep, there are four separate places where files related to 42GNUstep are installed: these places are called "domains". These four 43domains are the System domain, the Network domain, the Local domain, 44and the User domain. Each of these domains serve a special purpose. 45 46You can install various things in each domain; for example 47applications, tools or libraries. Each domain should allow you to 48install the different types of resources or compiled software. 49 50Starting with gnustep-make version 2.0, each GNUstep installation can 51specify how these domains should be organized and mapped to 52directories on the filesystem. A way to map GNUstep domains to 53filesystem directories is called a ``filesystem layout''. A 54filesystem layout will specify in which directory System Tools are to 55be installed, for example. The description of various filesystem 56layouts (and instructions on how to create your own) can be found in 57the @file{FilesystemLayouts} directory inside gnustep-make. 58 59Applications, libraries, bundles and other resources are normally 60looked up in domains following a fixed order: User first, then Local, 61then Network, then System. 62 63In this document we give a general overview of the GNUstep domains and 64of the interesting locations in a domain. We also describe the 65GNUstep filesystem layout. 66 67The GNUstep filesystem layout is a good way to discuss domains, 68because it is very simple: in the GNUstep filesystem layout, every 69domain is mapped to a single directory on disk. For example, the 70System domain could be mapped to the @file{/usr/GNUstep/System} 71directory, and everything that is installed into the System domain is 72then installed into some subdirectory of @file{/usr/GNUstep/System}. 73Before gnustep-make version 2.0, this was the only filesystem layout 74available. 75 76Please keep in mind that (starting from gnustep-make version 2.0) this 77is not the case for a general filesystem layout; for example a typical 78FHS (Unix) layout might be installing System Tools in @file{/usr/bin} 79and System Admin Tools in @file{/sbin}. 80 81In fact, starting with gnustep-make version 2.6.0, the default 82filesystem layout is now the FHS (Unix) layout rooted in 83@file{/usr/local}. 84 85@node The System Domain, The Local Domain, Top, Top 86@section The System Domain 87 88The System domain contains all files which were included in the 89default GNUstep installation or distribution. These files are 90normally managed by the distribution/packaging system used to install 91GNUstep; thus, making modifications to these files is highly 92discouraged. In addition, only the system administrator ('root' on 93most UNIX systems) should have permissions to write to that domain. 94 95Normally you can expect to find gnustep-make and the basic GNUstep 96libraries (Foundation and AppKit) in this domain, and also essential 97system applications (the Workspace Manager, the Editor, applications 98related to system administrative tasks), developer applications 99(Project Center and Gorm, as well as header files), essential 100extensions (bundles for XML, SSL, RTF, etc), as well as all software 101installed by the manufacturer of your distribution. 102 103In the GNUstep filesystem layout, the entire System domain is found in 104the @file{System} folder of the GNUstep installation. 105 106 107@node The Local Domain, The Network Domain, The System Domain, Top 108@section The Local Domain 109 110The Local domain is meant as the location for installing software 111which was not included with your GNUstep distribution and which you or 112your local sysadmin compile and/or install manually. These may 113include third party applications, custom extension libraries and their 114related header files, etc. Every software (except for gnustep-make, 115gnustep-base, gnustep-gui and gnustep-back which for historical 116reasons by default install into the System domain) should install by 117default into the Local domain, so that if you download a source 118tarball of the software and you install it, it installs by default in 119the right place for this operation (the Local domain). Distributions 120should override this default manually when they package the software 121they want to distribute as part of their distribution, so that in that 122case the software is installed in the System domain. 123 124In the GNUstep filesystem layout the entire Local domain is installed 125as the @file{Local} folder of your GNUstep installation. 126 127@node The Network Domain, The Users Domain, The Local Domain, Top 128@section The Network Domain 129 130The @file{Network} domain is optional and is usually coalesced with 131the @file{Local} domain by default; this is particularly appropriate 132for use on stand alone systems such as your home workstation. 133However, the Network domain can be of great use in networked, 134corporate environments. Its main purpose is to hold files exported 135from a central server in your network or from other workstations. 136Most times, remote directories containing applictations or general 137data used by several workstations in the network are mounted using the 138Network File System (NFS). Such usage gives administrators the 139possibility of providing application or resources to a vast number of 140workstations while only having to manage the software in one place. 141This is especially useful when workstations are used by several users 142with different tasks and requirements. If you want to take advantage 143of the Network domain, you need to use a filesystem layout with 144a separate Network domain. 145 146In the GNUstep filesystem layout the Network domain is the same as the 147Local domain; if you want to use the Network domain there is a 148separate GNUstep filesystem layout variant with a separate Network 149domain, in which case the entire Network domain is installed as the 150@file{Network} folder of your GNUstep installation. 151 152 153@node The Users Domain, Structure of a Domain, The Network Domain, Top 154@section The Users Domain 155 156The main purpose of the Users domain is to hold GNUstep related files 157which shall not be available to other users on the system but only to 158the user owning them. This includes the GNUstep defaults database 159(which holds system settings, application preferences and customized 160resources) as well as temporary data related to services and file type 161associations for programs. It also holds user installed applications 162and tools (each user has the ability to install their own version of 163an application or tool). 164 165In the GNUstep filesystem layout (and in most other layouts too) the 166User domain is completely contained in a subdirectory of the user's 167home directory called @file{GNUstep}. 168 169@node Structure of a Domain, Configuration, The Users Domain, Top 170@section Structure of a Domain 171 172In this section we examine the interesting locations in a domain. We 173will enumerate the locations, and discuss what should be installed in 174each location, and how they are mapped to directories on disk in the 175GNUstep filesystem layout and in a general filesystem layout. 176 177@menu 178* The GNUstep Filesystem Layout:: 179* Accessing Domain Locations:: 180* Applications:: 181* Admin Applications:: 182* Web Applications:: 183* Tools:: 184* Admin Tools:: 185* Library:: 186* Headers:: 187* Libraries:: 188* Documentation:: 189* Documentation (Info):: 190* Documentation (Man Pages):: 191* Folders inside Library:: 192@end menu 193 194@node The GNUstep Filesystem Layout, Accessing Domain Locations, Structure of a Domain, Structure of a Domain 195@subsection The GNUstep Filesystem Layout 196 197We quickly present the GNUstep filesystem layout for a domain first 198because it is an essential reference for all discussions on the 199structure of a domain. 200 201The GNUstep filesystem layout is the simplest layout, in which every 202domain is a directory on disk, and all locations in the domain are 203subdirectories of the domain. 204 205In that case, a domain has the following structure on disk: 206@example 207 Domain/ 208 Applications/ 209 Applications/Admin/ 210 Defaults/ (User domain only) 211 Library/ 212 Library/ApplicationSupport/ 213 Library/ApplicationSupport/Palettes 214 Library/Bundles/ 215 Library/Documentation/ 216 Library/Documentation/info/ 217 Library/Documentation/man/ 218 Library/Frameworks/ 219 Library/Headers/ 220 Library/Libraries/ 221 Library/Libraries/Java/ 222 Library/Libraries/Resources/ 223 Library/Makefiles/ (System domain only) 224 Library/Services/ 225 Library/Tools/Resources/ 226 Library/WebApplications/ 227 Tools/ 228 Tools/Admin/ 229@end example 230 231The terminology for locations is derived from this filesystem layout, 232and it can be useful to use this directory structure as a reference 233point for all discussions. For example, every domain must have a 234'Library' location. 235 236@node Accessing Domain Locations, Applications, The GNUstep Filesystem Layout, Structure of a Domain 237@subsection Accessing Domain Locations 238 239In order to install and run software that uses some resources, you 240need to be able to install the resources in the appropriate location, 241and your software needs to be able to locate these resources when it's 242running. 243 244Since domain locations can be mapped to arbitrary locations on disk, 245you must use the appropriate gnustep-make and gnustep-base facilities 246to install things in the right place and to find things at runtime. 247 248GNUstep-make creates makefile variables for all the domain locations. 249If you need to perform some custom installation for your software, you 250must use these variables to make sure your installation will work with 251all filesystem layouts. For example, the @file{Applications} location 252for the domain where the software will be installed is available as 253the @code{GNUSTEP_APPS} variable. You can also access the locations 254for specific domains by using the variables 255@code{GNUSTEP_SYSTEM_APPS}, @code{GNUSTEP_NETWORK_APPS}, 256@code{GNUSTEP_LOCAL_APPS} and @code{GNUSTEP_USER_APPS}. 257 258GNUstep-base provides you with the 259@code{NSSearchPathForDirectoriesInDomains()} function that allows you 260to retrieve the domain locations at runtime. You must lookup 261resources only via this function. For example, the 262@file{Applications} location can be found by using the 263@code{NSApplicationDirectory} directory key, so you can use it in your 264software to iterate over all the @file{Applications} directories in 265the various domains searching for an application. 266 267In general, all interesting domain locations have a set of variables 268defined in gnustep-make (such as @code{GNUSTEP_APPS}, 269@code{GNUSTEP_SYSTEM_APPS}, @code{GNUSTEP_NETWORK_APPS}, 270@code{GNUSTEP_LOCAL_APPS} and @code{GNUSTEP_USER_APPS}) and a 271corresponding directory key in gnustep-base (such as 272@code{NSApplicationDirectory}). 273 274When examining the various domain locations, we will explicitly 275mention the gnustep-make variables and the gnustep-base directory keys 276that can be used to access them. 277 278 279@node Applications, Admin Applications , Accessing Domain Locations, Structure of a Domain 280@subsection Applications 281 282The @file{Applications} location contains applications. Applications 283are programs that typically have a GUI interface and contain 284associated resource files, such as images, localization files and 285other program elements. 286 287Important applications which are part of GNUstep and which are often 288distributed as part of a core GNUstep distribution include: 289@example 290Gorm.app 291ProjectCenter.app 292GWorkspace.app 293Preferences.app 294@end example 295 296In GNUmakefiles, the @file{Applications} location is available via the 297@code{GNUSTEP_APPS} variable, which is the Applications location for 298the domain in which the software will be installed. You can also 299reference the locations in the various domains directly by using the 300variables @code{GNUSTEP_SYSTEM_APPS}, @code{GNUSTEP_NETWORK_APPS}, 301@code{GNUSTEP_LOCAL_APPS} and @code{GNUSTEP_USER_APPS}. 302 303In gnustep-base, the @file{Applications} locations are available by 304using the @code{NSApplicationDirectory} directory key for 305@code{NSSearchPathForDirectoriesInDomains()}. 306 307 308@node Admin Applications, Web Applications, Applications, Structure of a Domain 309@subsection Admin Applications 310 311The @file{Admin Applications} location contains applications that are 312only useful to the system administrator. A normal user wouldn't have 313enough privileges to use these applications in a useful way. 314 315In GNUmakefiles, the @file{Admin Applications} location is available 316via the @code{GNUSTEP_ADMIN_APPS} variable, which is the Admin 317Applications location for the domain in which the software will be 318installed. You can also reference the locations in the various 319domains directly by using the variables 320@code{GNUSTEP_SYSTEM_ADMIN_APPS}, @code{GNUSTEP_NETWORK_ADMIN_APPS}, 321@code{GNUSTEP_LOCAL_ADMIN_APPS} and @code{GNUSTEP_USER_ADMIN_APPS}. 322 323In gnustep-base, the @file{Admin Applications} locations are available 324by using the @code{NSAdminApplicationDirectory} directory key for 325@code{NSSearchPathForDirectoriesInDomains()}. 326 327 328@node Web Applications, Tools, Admin Applications, Structure of a Domain 329@subsection Web Applications 330 331The @file{Web Applications} location contains web applications that 332were created using GSWeb or SOPE. These are programs contained with 333their resources in small wrappers very similar to standard 334applications. 335 336In GNUmakefiles, the @file{Web Applications} location is available via 337the @code{GNUSTEP_WEB_APPS} variable, which is the Web Applications 338location for the domain in which the software will be installed. You 339can also reference the locations in the various domains directly by 340using the variables @code{GNUSTEP_SYSTEM_WEB_APPS}, 341@code{GNUSTEP_NETWORK_WEB_APPS}, @code{GNUSTEP_LOCAL_WEB_APPS} and 342@code{GNUSTEP_USER_WEB_APPS}. 343 344In gnustep-base, the @file{Web Applications} locations are available 345by using the @code{GSWebApplicationDirectory} directory key for 346@code{NSSearchPathForDirectoriesInDomains()}. 347 348 349@node Tools, Admin Tools, Web Applications, Structure of a Domain 350@subsection Tools 351 352The @file{Tools} location contains tools and executable scripts. Tools 353are programs which generally have a command-line interface. Most are 354not meant to be used by the average user. 355 356Important tools which are part of GNUstep and which are often 357distributed as part of a core GNUstep distribution include: 358@example 359openapp 360defaults 361gdomap 362gdnc 363gpbs 364@end example 365 366In GNUmakefiles, the @file{Tools} location is available via the 367@code{GNUSTEP_TOOLS} variable, which is the location for the domain in 368which the software will be installed. You can also reference the 369locations in the various domains directly by using the variables 370@code{GNUSTEP_SYSTEM_TOOLS}, @code{GNUSTEP_NETWORK_TOOLS}, 371@code{GNUSTEP_LOCAL_TOOLS} and @code{GNUSTEP_USER_TOOLS}. 372 373In gnustep-base, the @file{Tools} locations are available by using the 374@code{GSToolsDirectory} directory key for 375@code{NSSearchPathForDirectoriesInDomains()}. 376 377 378@node Admin Tools, Library, Tools, Structure of a Domain 379@subsection Admin Tools 380 381The @file{Admin Tools} location contains tools and executable scripts 382that are only useful to the system administrator. A normal user 383wouldn't have enough privileges to use these applications in a useful 384way. 385 386In GNUmakefiles, the @file{Admin Tools} location is available via the 387@code{GNUSTEP_ADMIN_TOOLS} variable, which is the location for the 388domain in which the software will be installed. You can also 389reference the locations in the various domains directly by using the 390variables @code{GNUSTEP_SYSTEM_ADMIN_TOOLS}, 391@code{GNUSTEP_NETWORK_ADMIN_TOOLS}, @code{GNUSTEP_LOCAL_ADMIN_TOOLS} 392and @code{GNUSTEP_USER_ADMIN_TOOLS}. 393 394In gnustep-base, the @file{Admin Tools} locations are available by 395using the @code{GSAdminToolsDirectory} directory key for 396@code{NSSearchPathForDirectoriesInDomains()}. 397 398 399@node Library, Headers, Admin Tools, Structure of a Domain 400@subsection Library 401 402The @file{Library} location contains most of the resources that are 403located and loaded at runtime. These resources are organized in 404folders (directories) inside @file{Library}; the most important 405@file{Library} folders will be described later on. 406 407Like all systems inspired by OpenStep, resources are mostly organized 408in bundles and small wrappers that contain both machine-dependent 409files (such as executables or loadable object files) and general 410machine-independent resources (such as images or text files). For 411this reason, the @file{Library} location will contain both 412machine-dependent and machine-independent files. 413 414The structure of the folders within Library is the same in all 415filesystem layouts, with a few exceptions: in the GNUstep filesystem 416layout, the @code{Libraries}, @code{Headers}, @code{Documentation} and 417@code{WebApplications} folders are all inside @code{Library}, but this 418is not necessarily true for other filesystem layouts. 419 420Vice versa, it's common on other filesystem layouts (eg, FHS) to put 421@code{Applications} and @code{Admin Applications} as folders inside 422@code{Library}. 423 424In GNUmakefiles, the @file{Library} location is available via the 425@code{GNUSTEP_LIBRARY} variable, which is the location for the 426domain in which the software will be installed. You can also 427reference the locations in the various domains directly by using the 428variables @code{GNUSTEP_SYSTEM_LIBRARY}, 429@code{GNUSTEP_NETWORK_LIBRARY}, @code{GNUSTEP_LOCAL_LIBRARY} and 430@code{GNUSTEP_USER_LIBRARY}. 431 432In gnustep-base, the @file{Library} locations are available by 433using the @code{NSLibraryDirectory} directory key for 434@code{NSSearchPathForDirectoriesInDomains()}. 435 436 437@node Headers, Libraries, Library, Structure of a Domain 438@subsection Headers 439 440The @code{Headers} location contains header files associated with a 441library located in @code{Libraries}. 442 443In GNUmakefiles, the @file{Headers} location is available via the 444@code{GNUSTEP_HEADERS} variable, which is the location for the 445domain in which the software will be installed. You can also 446reference the locations in the various domains directly by using the 447variables @code{GNUSTEP_SYSTEM_HEADERS}, 448@code{GNUSTEP_NETWORK_HEADERS}, @code{GNUSTEP_LOCAL_HEADERS} and 449@code{GNUSTEP_USER_HEADERS}. 450 451In gnustep-base, the @file{Headers} location is not currently 452available. 453 454 455@node Libraries, Documentation, Headers, Structure of a Domain 456@subsection Libraries 457 458The @code{Libraries} location contains libraries (shared/static object 459files that are linked into programs). (NOTE: In the GNUstep 460filesystem layout, the Libraries directory being in Library may sound 461somewhat redundant, however, it could be read as "a Library of shared 462libraries"). 463 464In the GNUstep filesystem layout, the @code{Library/Libraries} folder 465contains two other folders: @code{Resources} and @code{Java}. It's 466important to notice that when the @code{Libraries} location is moved 467elsewhere, these folders are not moved; they will still be in 468@code{Library/Libraries/Resources} and @code{Library/Libraries/Java}. 469 470In GNUmakefiles, the @file{Libraries} location is available via the 471@code{GNUSTEP_LIBRARIES} variable, which is the location for the 472domain in which the software will be installed. You can also 473reference the locations in the various domains directly by using the 474variables @code{GNUSTEP_SYSTEM_LIBRARIES}, 475@code{GNUSTEP_NETWORK_LIBRARIES}, @code{GNUSTEP_LOCAL_LIBRARIES} and 476@code{GNUSTEP_USER_LIBRARIES}. 477 478In gnustep-base, the @file{Libraries} locations are available by using 479the @code{GSLibrariesDirectory} directory key for 480@code{NSSearchPathForDirectoriesInDomains()}. 481 482 483@node Documentation, Documentation (Info), Libraries, Structure of a Domain 484@subsection Documentation 485 486The @code{Documentation} location contains documentation for 487libraries, applications, etc. 488 489In GNUmakefiles, the @file{Documentation} location is available via 490the @code{GNUSTEP_DOC} variable, which is the location for the 491domain in which the software will be installed. You can also 492reference the locations in the various domains directly by using the 493variables @code{GNUSTEP_SYSTEM_DOC}, @code{GNUSTEP_NETWORK_DOC}, 494@code{GNUSTEP_LOCAL_DOC} and @code{GNUSTEP_USER_DOC}. 495 496In gnustep-base, the @file{Documentation} locations are available by 497using the @code{NSDocumentationDirectory} directory key for 498@code{NSSearchPathForDirectoriesInDomains()}. 499 500 501@node Documentation (Info), Documentation (Man Pages), Documentation, Structure of a Domain 502@subsection Documentation (Info) 503 504The @code{Documentation (Info)} location contains documentation in 505info format. 506 507In GNUmakefiles, the @file{Documentation (Info)} location is available 508via the @code{GNUSTEP_DOC_INFO} variable, which is the location for 509the domain in which the software will be installed. You can also 510reference the locations in the various domains directly by using the 511variables @code{GNUSTEP_SYSTEM_DOC_INFO}, 512@code{GNUSTEP_NETWORK_DOC_INFO}, @code{GNUSTEP_LOCAL_DOC_INFO} and 513@code{GNUSTEP_USER_DOC_INFO}. 514 515In gnustep-base, the @file{Documentation (Info)} locations are not 516currently available. 517 518 519@node Documentation (Man Pages), Folders inside Library, Documentation (Info), Structure of a Domain 520@subsection Documentation (Man Pages) 521 522 523The @code{Documentation (Man Pages)} location contains Unix man pages. 524 525In GNUmakefiles, the @file{Documentation (Man Pages)} location is 526available via the @code{GNUSTEP_DOC_MAN} variable, which is the 527location for the domain in which the software will be installed. You 528can also reference the locations in the various domains directly by 529using the variables @code{GNUSTEP_SYSTEM_DOC_MAN}, 530@code{GNUSTEP_NETWORK_DOC_MAN}, @code{GNUSTEP_LOCAL_DOC_MAN} and 531@code{GNUSTEP_USER_DOC_MAN}. 532 533In gnustep-base, the @file{Documentation (Man)} locations are not 534currently available. 535 536 537@node Folders inside Library, , Documentation (Man Pages), Structure of a Domain 538@subsection Folders inside Library 539 540In this section we discuss the standard folders that are available 541inside the @code{Library} location. To find any of these folders, 542just find the location of @code{Library} and then append the folder 543name (for example, in a GNUmakefile you can access the 'ColorPickers' 544folder of the installation domain as 545@code{$GNUSTEP_LIBRARY/ColorPickers}). 546 547Some of the folders can also be accessed using direct variables, such 548as @code{GNUSTEP_BUNDLES}. You should prefer using these direct 549variables if you can because they are more future-proof (in case some 550of the folders become independent from @code{Library} in the future). 551All such cases should be documented here. 552 553@menu 554* ApplicationSupport:: 555* Bundles:: 556* ColorPickers:: 557* Colors:: 558* DTDs:: 559* DocTemplates:: 560* Fonts:: 561* Frameworks:: 562* Images:: 563* Libraries/Java:: 564* Libraries/Resources:: 565* KeyBindings:: 566* PostScript:: 567* Services:: 568* Sounds:: 569* Tools/Resources:: 570@end menu 571 572@node ApplicationSupport, Bundles, Folders inside Library, Folders inside Library 573@subsubsection ApplicationSupport 574 575This directory contains bundles and other resources that are provided 576for an application, but that are not specifically distributed with 577that application. For instance, these may be third-party resources for 578an application. 579 580For example, modules for the Preferences application may be stored 581here, in a @file{Preferences} subdirectory. In particular, Palettes 582for Gorm are stored in @file{ApplicationSupport/Palettes}. 583 584In GNUmakefiles, this location is available via the 585@code{GNUSTEP_APPLICATION_SUPPORT} variable, which is the location for 586the domain in which the software will be installed. You can also 587reference the locations in the various domains directly by using the 588variables @code{GNUSTEP_SYSTEM_APPLICATION_SUPPORT}, 589@code{GNUSTEP_NETWORK_APPLICATION_SUPPORT}, 590@code{GNUSTEP_LOCAL_APPLICATION_SUPPORT} and 591@code{GNUSTEP_USER_APPLICATION_SUPPORT}. 592 593In gnustep-base, the @code{ApplicationSupport} locations are available 594by using the @code{NSApplicationSupportDirectory} directory key for 595@code{NSSearchPathForDirectoriesInDomains()}. 596 597@node Bundles, ColorPickers, ApplicationSupport, Folders inside Library 598@subsubsection Bundles 599 600This directory contains bundles. Bundles are collections of executable 601code and associated resources that may be loaded at runtime by an 602application or tool. Note: this directory is depreciated. Use 603ApplicationSupport to install bundles that can be used by an 604application. 605 606In GNUmakefiles, this location is available via the 607@code{GNUSTEP_BUNDLES} variable, which is the location for the domain 608in which the software will be installed. You can also reference the 609locations in the various domains directly by using the variables 610@code{GNUSTEP_SYSTEM_BUNDLES}, @code{GNUSTEP_NETWORK_BUNDLES}, 611@code{GNUSTEP_LOCAL_BUNDLES} and @code{GNUSTEP_USER_BUNDLES}. 612 613In gnustep-base, you can access the @code{Bundles} location as a 614folder inside the @code{Library} location. 615 616 617@node ColorPickers, Colors, Bundles, Folders inside Library 618@subsubsection ColorPickers 619 620This directory contains bundles that are used by the color picking 621system. They may include code that implements picking colors from a 622color wheel, a custom defined list of colors, etc. 623 624This folder is accessed as the @code{ColorPickers} folder inside 625@code{Library}. 626 627@node Colors, DTDs, ColorPickers, Folders inside Library 628@subsubsection Colors 629 630This directory contains files that define specific color mappings for 631use within libraries or applications that require color definitions. 632 633This folder is accessed as the @code{Colors} folder inside 634@code{Library}. 635 636@node DTDs, DocTemplates, Colors, Folders inside Library 637@subsubsection DTDs 638 639This directory contains any Document Type Definitions 640required for document parsing. 641 642This folder is accessed as the @code{DTDs} folder inside 643@code{Library}. 644 645@node DocTemplates, Fonts, DTDs, Folders inside Library 646@subsubsection DocTemplates 647 648This directory contains text templates for automatic documentation, as 649generated by autodoc. Any additional documentation template types 650must be placed in this directory, as a central location for 651documentation template types. Any templates installed within this 652directory must have an extension indicating what type of documentation 653system it is referenced by (ie. .gsdoc for the GNUstep implementation 654of autodoc). 655 656This folder is accessed as the @code{DocTemplates} folder inside 657@code{Library}. 658 659@node Fonts, Frameworks, DocTemplates, Folders inside Library 660@subsubsection Fonts 661 662This directory contains fonts and files for organizing font information. 663 664This folder is accessed as the @code{Fonts} folder inside 665@code{Library}. 666 667@node Frameworks, Images, Fonts, Folders inside Library 668@subsubsection Frameworks 669 670This directory contains frameworks. Frameworks are a type of bundle, 671which include, within their directory structure, a shared library 672providing a specific functionality (or group of related 673functionalities), and all resources required by that shared library. 674 675All frameworks must have the extension @file{framework}, to indicate 676their usage. 677 678Use of frameworks is generally discouraged, as it is difficult to 679support them in a clean way on multiple platforms. Bundles are a 680better method of organizing shared collections of resources and code. 681 682In GNUmakefiles, this location is available via the 683@code{GNUSTEP_FRAMEWORKS} variable, which is the location for the 684domain in which the software will be installed. You can also 685reference the locations in the various domains directly by using the 686variables @code{GNUSTEP_SYSTEM_FRAMEWORKS}, 687@code{GNUSTEP_NETWORK_FRAMEWORKS}, @code{GNUSTEP_LOCAL_FRAMEWORKS} and 688@code{GNUSTEP_USER_FRAMEWORKS}. 689 690In gnustep-base, the @code{Frameworks} locations are available by 691using the @code{GSFrameworksDirectory} directory key for 692@code{NSSearchPathForDirectoriesInDomains()}. 693 694@node Images, Libraries/Java, Frameworks, Folders inside Library 695@subsubsection Images 696 697@node Libraries/Java, Libraries/Resources, Images, Folders inside Library 698@subsubsection Libraries/Java 699 700This directory contains Java classes. If you are using Java with 701GNUstep, you probably want to make sure these directories are in your 702CLASSPATH. 703 704In GNUmakefiles, this location is available via the 705@code{GNUSTEP_JAVA} variable, which is the location for the domain in 706which the software will be installed. You can also reference the 707locations in the various domains directly by using the variables 708@code{GNUSTEP_SYSTEM_JAVA}, @code{GNUSTEP_NETWORK_JAVA}, 709@code{GNUSTEP_LOCAL_JAVA} and @code{GNUSTEP_USER_JAVA}. 710 711In gnustep-base, you can access the @code{Libraries/Java} location as 712the @code{Libraries/Java} folder inside the @code{Library} location. 713 714@node Libraries/Resources, KeyBindings, Libraries/Java, Folders inside Library 715@subsubsection Libraries/Resources 716 717This directory contains resources used by shared libraries. In 718GNUstep a shared library can have an associated resource bundle (a 719bundle only composed of resources, with no object file), which is then 720installed into this directory. 721 722For example, @code{gnustep-base} will get its resource bundle 723installed into 724@code{GNUSTEP_SYSTEM_LIBRARY/Libraries/Resources/gnustep-base}. 725 726In GNUmakefiles, this location is available via the 727@code{GNUSTEP_RESOURCES} variable, which is the location for the 728domain in which the software will be installed. You can also 729reference the locations in the various domains directly by using the 730variables @code{GNUSTEP_SYSTEM_RESOURCES}, 731@code{GNUSTEP_NETWORK_RESOURCES}, @code{GNUSTEP_LOCAL_RESOURCES} and 732@code{GNUSTEP_USER_RESOURCES}. 733 734In gnustep-base, you can access the resource bundle associated with a 735library by using the @code{[NSBundle +bundleForLibrary:]} method (it 736is a GNUstep extension). 737 738@node KeyBindings, PostScript, Libraries/Resources, Folders inside Library 739@subsubsection KeyBindings 740 741@node PostScript, Services, KeyBindings, Folders inside Library 742@subsubsection PostScript 743 744This directory contains directories for specific PostScript document 745types and definitions, allowing applications written using the GNUstep 746development environment to display PostScript documents, or 747communicate with printers using PostScript. 748 749This folder is accessed as the @code{PostScript} folder inside 750@code{Library}. 751 752@node Services, Sounds, PostScript, Folders inside Library 753@subsubsection Services 754 755This directory contains bundles that are specifically built to provide 756functionality between different programs (for example, spell checking, 757creation of a note from text within an email application). Services 758that are installed on the system must an extension of ".service". 759 760In GNUmakefiles, this location is available via the 761@code{GNUSTEP_SERVICES} variable, which is the location for the domain 762in which the software will be installed. You can also reference the 763locations in the various domains directly by using the variables 764@code{GNUSTEP_SYSTEM_SERVICES}, @code{GNUSTEP_NETWORK_SERVICES}, 765@code{GNUSTEP_LOCAL_SERVICES} and @code{GNUSTEP_USER_SERVICES}. 766 767In gnustep-base, you can access the @code{Services} location as a 768folder inside the @code{Library} location. 769 770@node Sounds, Tools/Resources, Services, Folders inside Library 771@subsubsection Sounds 772 773This directory contains sound files. 774 775@node Tools/Resources, , Sounds, Folders inside Library 776@subsubsection Tools/Resources 777 778This directory contains resources used by tools. In GNUstep a tool 779can have an associated resource bundle (a bundle only composed of 780resources, with no object file), which is then installed into this 781directory. 782 783For example, a tool called @code{myTool} will get its resource bundle 784installed into 785@code{GNUSTEP_SYSTEM_LIBRARY/Tools/Resources/myTool}. 786 787In GNUmakefiles, this location is available as the 788@file{Tools/Resources} folder inside the @code{Library} location. 789 790In gnustep-base, you can access the resource bundle associated with 791your tool by using the @code{[NSBundle +mainBundle]} method (this 792semantic is a GNUstep extension). 793 794@c TODO: Mention special directories, for example location of user defaults 795@c TODO: Mention special directories, for example location of makefiles 796 797 798@node Configuration, , Structure of a Domain, Top 799@section Configuration 800 801GNUstep supports arbitrary filesystem layouts to map the locations in 802the various domains to directories on the filesystem. 803 804When you run gnustep-make's ./configure program you can use the 805--with-layout=xxx flag to select the filesystem layout that you prefer 806(choosing between the ones in the FilesystemLayouts directory, or 807creating your own in there!). 808 809For most users, this is all they need to know. 810 811In this section we'll go more into the details of how the filesystem 812layout system internally works; this is only useful if you need to do 813something advanced with it, typically because you have multiple 814GNUstep installations or you are trying to do some custom packaging of 815GNUstep. 816 817The filesystem layout is determined by the GNUstep configuration file 818(or if that is not present, by default values built into the GNUstep 819make and base packages when they were configured and built). 820 821The location of the GNUstep configuration file is built in to the make and 822base packages when they are configured using the --with-config-file option 823to the configure script. The path specified must be an absolute one for 824the make package, but may also be a path relative to the location of the 825base library itsself (as dynamically linked into applications) for the 826base package. 827 828However, the location of the configuration file may also be specified 829using the GNUSTEP_CONFIG_FILE environment variable, overriding the value 830built in to the package, at any time when using the make package to build 831or install software. Support for the environment variable may also 832be enabled for the make package when its configure script is run. 833 834The GNUSTEP_CONFIG_FILE environment variable is particularly useful if 835you have multiple installations and need to easily switch between 836them. 837 838@menu 839* File Format:: 840* Windows (MINGW):: 841@end menu 842 843@node File Format, Windows (MINGW), Configuration, Configuration 844@subsection File Format 845 846By default, the configuration file is called GNUstep.conf; it 847typically exists in /etc/GNUstep or /usr/local/etc/GNUstep (depending 848on how gnustep-make was configured) on a Unix-like system. This file 849is in a format suitable for being 'sourced' by the standard unix 850(Bourne) shell, consisting of lines of the form key=value, comments 851(everything on a line from the first hash (#) onwards), or blank 852lines. 853 854This is very convenient on unix-like systems, but needs care for windows users. 855If a value contains whitespace or backslash characters (or the hash which 856would start a comment) it needs to be quoted by enclosing the whole value 857in single or double quotes. An alternative for values containing backslashes 858(the norm for a windows path) is to double up each backslash in an unquoted 859value. 860 861The valid values for the keys in the GNUstep configuration file are 862documented in the GNUstep.conf file itself. Please check the 863GNUstep.conf.in file in your gnustep-make distribution for an 864up-to-date list of all the variables that you can change with 865explanations of what they do. 866 867@node Windows (MINGW), , File Format, Configuration 868@subsection Windows (MINGW) 869 870On ms-windows, for software development, you are likely to want to have an 871extra configuration file. This is because of the limitations of the 872make program (used to build and install software). 873 874Basically the issue is that the make package doesn't really like the 875colons and backslashes in windows paths (using them is error prone) 876and can't tolerate whitespace in file names. So you want to do all 877the building in a unix-style environment using only unix-style paths. 878 879On MSYS/MinGW this is done naturally by using the standard unix-style 880/usr/local/etc/GNUstep/GNUstep.conf config file, where the location is 881inside the MSYS unix-style emulation system. This is what is normally 882done by gnustep-make, so there is nothing special you need to do here. 883 884On the other hand, the base library (and all applications since they are 885built using it) wants to work with native windows paths so that applications 886behave naturally as far as the end users are concerned, and therefore needs a 887configuration file containing windows-style paths rather than unix-like 888ones. 889 890So, you need a different config file to be used by gnustep-base at 891runtime. And this is enabled by default -- in fact gnustep-base will 892use ./GNUstep.conf as config file on MinGW, where the location is 893relative to the location of the gnustep-base.dll. 894 895In other words, gnustep-make will use 896C:/xxx/usr/local/etc/GNUstep/GNUstep.conf (where 'xxx' is the MSYS 897installation path), while gnustep-base will use a GNUstep.conf file in 898the same directory as the gnustep-base.dll. 899 900This ./GNUstep.conf file normally does not even exist; gnustep-base's 901./configure will hardcode into gnustep-base.dll relative paths to all 902resources (relative from the installation location of 903gnustep-base.dll). If you modify the filesystem layout or relocate 904gnustep-base.dll, you should add a GNUstep.conf file with 905gnustep-base.dll that contains the relative locations of the 906directories (relative to the location of gnustep-base.dll). 907 908It is recommended that this ./GNUstep.conf always contains relative 909paths to make relocation easier. 910 911@bye 912\bye 913