gnustep/tools-make
0
0
Fork 0
mirror of https://github.com/gnustep/tools-make.git synced 2025-04-23 22:33:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added documentation on how to create packages

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/tools/make/trunk@27330 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Nicola Pero 2008-12-18 13:17:21 +00:00
parent 1762b8cdc3
commit 1ed8f5be70
2 changed files with 387 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
ChangeLog
View file

@ -1,3 +1,9 @@
2008-12-18 Nicola Pero <nicola.pero@meta-innovation.com>
* Documentation/README.Packaging: New file providing complete
instructions and recommendations on how to create GNUstep
packages.
2008-12-05 Richard Frith-Macdonald <rfm@gnu.org>
* GNUstep.sh.in:

381
Documentation/README.Packaging Normal file
View file

@ -0,0 +1,381 @@
Date: 18-Dec-2008
Author: Nicola Pero <nicola.pero@meta-innovation.com>
PURPOSE
-------
This document is intended to provide background information useful to
successfully package GNUstep. It particularly applies to GNU/Linux
packages such as RPMs and DEBs, but the general concepts would apply
to most type of packaging. If you're packaging for other systems,
such as Microsoft Windows, you should read carefully the instructions
for that system as well as there will be significant differences.
DESTDIR
-------
gnustep-make and all the GNUstep software supports the standard
variable DESTDIR to relocate the installation into a packaging
directory. You need to pass it when running a 'make install', as in
make install DESTDIR=/tmp/package/
this example will cause all the software to be installed in
subdirectories of /tmp/package; for example, a config file that would
normally be installed into /etc/GNUstep/GNUstep.conf will be installed
into /tmp/package/etc/GNUstep/GNUstep.conf.
To create a package, you then only need to package all the files
that were installed into that directory.
GNUSTEP-MAKE
------------
When packaging GNUstep, you should start by packaging gnustep-make.
GNUstep-make includes both the basic filesystem layout configuration
files and scripts that are used by all the other GNUstep software, and
makefiles and scripts that are used to build GNUstep software. It
would make sense to have them as separate packages (eg, a
"gnustep-filesystem" for all users and a "gnustep-make" package for
developers), but at this stage for simplicity we recommend just having
a single package that includes both.
All your GNUstep packages should depend on gnustep-make (which
includes the filesystem layout infrastructure) and gnustep-base (which
includes the basic Objective-C foundation library that everything else
uses).
GNUstep-make has a number of configure options. Most of them affect
all other GNUstep software. The defaults should be fine in most
situations, except for the filesystem layout which you really need to
review. If you are confused by an option and it's not mentioned in
this document, we recommend using whatever default is automatically
selected by gnustep-make.
The minimal set of configure options that you need is probably just
./configure --with-layout={FILE}
Read the section 1. FILESYSTEM LAYOUT for a bit of help on choosing
your filesystem layout.
If you have a bit more time, it's probably worth checking the other
available options as well and thinking if you need or want to change
any of them to better suit your environment. You probably don't, but
we document here the major options that you may want to change.
1. FILESYSTEM LAYOUT
====================
The first and most important configuration option is the filesystem
layout one:
./configure --with-layout={FILE}
Where {FILE} is the name of a file from the FilesystemLayouts
directory (eg, ./configure --with-layout=gnustep).
This option controls where GNUstep applications, tools, libraries, and
everything else GNUstep is installed.
There are two major options here:
1. The "standard" GNUstep layout, where all the GNUstep software is
installed into a separate directory tree (located by default in
/usr/GNUstep, but you can change this). This directory tree is
organized with directories such as Applications, Library, Tools and it
looks very much like a NeXTSTEP or an Apple Mac OS X filesystem. The
main disadvantage of this layout is that it doesn't blend so well with
the native Unix filesystem so it requires additional handling of
executable and library paths to get the system to find the executables
and the libraries.
2. The "FHS" layout, where the GNUstep software is installed into the
standard Unix directories such as /usr/bin and /usr/lib. This blends
very well with the native Unix filesystem, but you lose the special
allure of the GNUstep layout.
We don't have a particular recommendation on what filesystem to use;
you should pick the one that best suits your system's philosophy. If
it's a GNUstep-based system, you are likely to want to use the GNUstep
layout; if it's a more general Unix system, you may want to use the
FHS layout and have the GNUstep packages install into the standard
Unix directories just like every other package, since this might feel
more natural to your users.
If you're packaging things for Apple, it's also possible to use the
Apple filesystem layout, but extra care is required in that situation
to avoid conflicting with the Apple software itself. This works best
if packaging a single piece of software (eg, Renaissance).
In some special cases you may be unhappy with the existing filesystem
layouts and may want to create your own. This is possible and easy by
creating a new FilesystemLayouts file; for more information, please
refer to the gnustep-make documentation.
Once you pick a filesystem layout and configure gnustep-make using it,
all of the GNUstep software will automatically use it.
2. FLATTENED AND MULTI-PLATFORM
===============================
Here it is very likely that the defaults (flattened layout, and no
multi-platform support) are exactly what you want, since they remove a
lot of complication for end-users.
In case you wonder what these options do, here's a quick summary. If
you disable the flattened layout GNUstep uses a "fat" directory
structure that can accomodate binaries for multiple architectures in
the same filesystem; by turning on the "multi-platform" support you
can then make it to choose which one to use at runtime, allowing you
to mount a single fat directory structure from the network on machines
with different architectures. This works best with the GNUstep
filesystem layout.
3. LIBRARY-COMBOS
=================
The library-combo defines the main components of your Objective-C
environment. Unless you're on Darwin or Apple, it's unlikely that you
ever need to bother with library-combos and the default gnu-gnu-gnu is
perfect for you.
"gnu-gnu-gnu" means that the system is using the GNU Objective-C
runtime library, the GNU foundation/base library, and the GNU app/gui
library. It is possible in some situations to replace some of these
components with Apple libraries, for example, eg, the apple-gnu-gnu
library combo would mean using the Apple Objective-C runtime library
instead of the GNU one.
4. CONFIGURATION FILE
=====================
GNUstep has a system-wide configuration file that is used by both
gnustep-make and gnustep-base to learn about the current filesystem
layout in the system and locate the various resources. By default,
this configuration file is installed by gnustep-make into
/etc/GNUstep/GNUstep.conf
This location can be changed as in
./configure --with-config-file=/etc/GNUstep.conf
Please note that this configuration file is generally not meant to be
edited after it's been installed by gnustep-make. The configuration
file merely records the filesystem layout that was chosen at configure
time and is used by all the software.
Finally, changing the location of the configuration file can introduce
an additional complication since you later need to make sure the new
config file is found in its new location. This should be easy and is
explained below, but it might depend on your setup. If you don't have
a serious reason to change its location, we recommend just leaving the
configuration file in the default /etc/GNUstep/GNUstep.conf location
which is guaranteed to work with no additional setup work.
5. USER DEFAULTS DIRECTORY
==========================
User defaults are used by GNUstep applications and tools to store your
user preferences and other user-specific information. These user
defaults are stored in a directory inside the user's home directory,
which by default is
~/GNUstep/Defaults/
You can change this to something else, for example
./configure --with-user-defaults-dir=.GNUstep/Defaults
would store the defaults into the directory ~/.GNUstep/Defaults.
If you change this, it might be worth testing it later; after you install
GNUstep-base, you can test where the user defaults get written by using
the command-line tool 'defaults' which allows you to read or write
user defaults.
6. SUMMARY OF CONFIGURE OPTIONS
===============================
If you've followed us up to here, probably your gnustep-make's configure
command now looks something like
./configure --with-layout={FILE}
Or, if you really wanted to change a lot of things, it might look like
./configure --with-layout={FILE} --with-config-file={LOCATION} --with-user-defaults-dir={DEFAULTS_DIR}
7. USER ENVIRONMENT
===================
GNUstep will install applications, tools and libraries into the
filesystem of your choice. If this filesystem is different from the
native system filesystem, it's likely that:
* executables won't be found because they are not in the user's PATH
* libraries won't be found because they are not in the user's LD_LIBRARY_PATH
(or in /etc/ld.so.conf or similar variables/configuration depending on the
type of system)
In that case you need to make sure that when the gnustep-make package
is installed, these paths will be added as appropriate.
One option is to use the GNUstep.sh script that comes with
GNUstep-make. You should execute it every time a user logs in, for
example by adding
. /usr/GNUstep/System/Library/Makefiles/GNUstep.sh
to your /etc/profile (or appropriate corresponding setup for your system).
The other option is to add manually the paths; check the documentation
for your filesystem layout for the paths that you need to add (see
FilesystemLayouts/ for the documentation of the various layouts).
8. DEVELOPER ENVIRONMENT
========================
To compile software that uses gnustep-make, you also need to set the
GNUSTEP_MAKEFILES shell variable:
GNUSTEP_MAKEFILES=/usr/GNUstep/System/Library/Makefiles
export GNUSTEP_MAKEFILES
(the actual location depends on your filesystem layout; please check
the output of gnustep-make's ./configure to see the location on your
chosen layout). If you're using GNUstep.sh, this variable is
automatically set by it; otherwise you need to make sure that after
installing your gnustep-make package, this variable is set in the
environment whenever a user logs in.
This is important because then users can download any GNUstep software
and compile it by just typing 'make'. And, of course, you can compile
the software yourself and create GNUstep packages. :-)
GNUSTEP_INSTALLATION_DOMAIN
---------------------------
Once you have packaged gnustep-make, you are ready to start packaging
all other GNUstep software, starting with gnustep-base.
By default, all GNUstep software will install into the "LOCAL" domain
if you compile it from source. Depending on your filesystem layout,
this is mapped to different directories on disk; with a GNUstep
filesystem layout it would typically be mapped to /usr/GNUstep/Local
and subdirectories, and with a FHS (Unix) filesystem layout it would
typically be mapped to /usr/local and subdirectories.
This is inappropriate for packages though; you want all of your
packages to install into the "SYSTEM" domain. Again, depending on
your filesystem layout, the "SYSTEM" domain is mapped to different
directories on disk; with a GNUstep filesystem layout it would
typically be mapped to /usr/GNUstep/System and subdirectories, and
with a FHS (Unix) filesystem layout it would typically be mapped to
/usr, /var and subdirectories.
To install software into the SYSTEM domain, you should use the
variable GNUSTEP_INSTALLATION_DOMAIN, as in
make install GNUSTEP_INSTALLATION_DOMAIN=SYSTEM
You can also set the variable in the shell (recommended), as in
GNUSTEP_INSTALLATION_DOMAIN=SYSTEM
export GNUSTEP_INSTALLATION_DOMAIN
make
make install
If you're packaging, you're likely to be also using the DESTDIR
variable, so your package build command sequence would probably look
like
DESTDIR=/tmp/my-package
export DESTDIR
GNUSTEP_INSTALLATION_DOMAIN=SYSTEM
export GNUSTEP_INSTALLATION_DOMAIN
make
make install
and then you have all the compiled software files inside
/tmp/my-package ready to be packaged.
Obviously some packages (but not all of them) require an initial
'configure' before the 'make' step, or require other minor changes
around this basic set of commands.
GNUSTEP-BASE
------------
Once you have packaged gnustep-make, your next step is to package
gnustep-base.
gnustep-base has a number of configure options that you may want to
check; most of them have to do with locating the various libraries on
your platform. The package build command sequence is the standard one
and so would look something like
DESTDIR=/tmp/my-package
export DESTDIR
GNUSTEP_INSTALLATION_DOMAIN=SYSTEM
export GNUSTEP_INSTALLATION_DOMAIN
./configure {maybe some options here}
make
make install
The only configure options that are really specific to GNUstep are the
ones controlling the location of the configuration file.
If you changed the location of the configuration file when you
configured gnustep-make by using the option --with-config-file as in
./configure --with-config-file=/etc/GNUstep.conf
then you need to make sure that gnustep-base's configure has found the
configuration file in its new location. Check the output of
gnustep-base's configure; it should mention your special configuration
file location.
If it doesn't, you may need to configure gnustep-base using the
--with-config-file option, as in
./configure --with-config-file=/etc/GNUstep.conf
to make sure the correct file is used.
OTHER GNUSTEP PACKAGES
----------------------
At this stage, all the GNUstep-specific issues should have been sorted
out and packaging GNUstep software should be quite easy. You just
need to use DESTDIR and GNUSTEP_INSTALLATION_DOMAIN=SYSTEM.