Notes on building Xenocara for OpenBSD X hackers
This document presents some techniques that can be useful for people
wanting to hack the xenocara tree. It assumes some basic knowledge of
the OpenBSD build system, as described in the release(8) manual page.
o About Xenocara
--------------
Xenocara is the name chosen for OpenBSD's version of X. It's
currently based on X.Org 7.2 and its dependencies. The goal of
Xenocara is to provide a framework to host local modifications and to
automate the build of the modular X.Org components, including 3rd
party packages and some software maintained by OpenBSD developers.
o Source tree
-----------
The organisation of the xenocara directory follows the general
organisation used in X.Org:
- app: X applications and utilities
- data: various data files (keyboard mappings and bitmaps)
- doc: documentation
- driver: input and video drivers
- font: fonts
- lib: libraries
- proto: X protocol headers
- util: utilities that don't fit anywhere else
- xserver: the source for the X servers
In addition Xenocara uses the following directories:
- dist: contains the Mesa sources, shared by lib and xserver above
- distrib: all binary distribution related tools and data
- etc: mtree(8) data files
- share: make(1) configuration for Xenocara
At the top-level directory two files describe the individual
components of Xenocara:
- MODULES lists all X.Org components (imported from the X.Org
distribution at http://xorg.freedesktop.org/archive/)
- 3RDPARTY lists all 3rd party software components provided in Xenocara,
either as dependencies of the X.Org software, or as
complements to it to provide a more useable default
environment.
o Compiling and installing
------------------------
Xenocara is made up of more than three hundred different
independent packages that need to be built and installed in the right
order, especially while bootstrapping (while /usr/X11R6 is still
empty). The Xenocara Makefiles take care of that using the 'build'
target.
Quick startup guide
The following steps will build and install everything for the first time.
cd xenocara
make bootstrap
make obj
make build
If you want to use another obj directory see below.
Requirements
A freshly checked out xenocara tree is buildable without any external
tool. However if you start modifying things in the automake build
system used by many packages, you will need to have the following
GNU autotools packages installed:
- automake 1.9 (devel/automake/1.9)
- autoconf 2.59 (devel/autoconf/2.59)
- metaauto 0.6 (or later) (devel/metaauto)
- libtool 1.5.22 (or later) (devel/libtool)
If you have your source tree on an NFS partition, make sure the clock
of your server and client are properly synchronised. A test run by
configure will fail if the drift is more than one second. And larger
drifts will cause other problems during builds anyways.
Path
To build Xenocara, you need to have /usr/X11R6/bin in your PATH.
Sudo
If the SUDO variable points to your sudo(8) binary in /etc/mk.conf,
'make build' can be run as a normal user. It will raise its privileges
whenever needed with sudo. Otherwise, you need to run make build as
root.
If you have installed the full Xenocara X sets on your system, you
don't need to build all of Xenocara to patch one element. You can go
to any module sub-directory and run 'make build' from there.
Source directory
The variable XSRCDIR can be set either in the environment or in
/etc/mk.conf to point to the xenocara source tree, in case you keep it
in a non-standard directory (the default is /usr/src/xenocara).
Objdirs
Xenocara supports objdirs (and it's even the recommended way to build
things). Just run 'make obj' at any level before 'make build' to make
sure that the object directories are created.
XOBJDIR defines the obj directory that is used (defaults to /usr/xobj).
It should be created before running 'make obj'.
Shadow trees
Alternatively, the old 'lndir(1)' method can still be used to build
Xenocara outside of its source tree. Just don't use 'make obj' in this
case.
o Regenerating configure scripts
------------------------------
Whenever you touched an import file for GNU autotools (Makefile.am,
configure.ac mostly), you need to rebuild the configure script and
makefiles skeletons. For that use the following command in the
directory where you edited the autotools source files:
env XENOCARA_RERUN_AUTOCONF=Yes make -f Makefile.bsd-wrapper build
You can also set XENOCARA_RERUN_AUTOCONF in /etc/mk.conf or in the
environment to force the regeneration of configure scripts
in every component during a make build.
o Cleaning in packages managed by autotools
-----------------------------------------
One common problem when building xenocara is the case where the obj
directory didn't exist (or the symbolic link pointed to a non-existent
directory) when the source was first built. After fixing this problem,
'configure' will refuse to work in the obj dir, because the source
is already configured.
To recover from this in one package:
rm -f obj
make -f Makefile.bsd-wrapper cleandir
mkdir XOBJDIR
make -f Makefile.bsd-wrapper obj
make -f Makefile.bsd-wrapper build
or from the root of the xenocara tree:
find . -type l -name obj | xargs rm -f
make cleandir
mkdir XOBJDIR
make obj
make build
for more desperate cases, remove all files from XSRCDIR not in CVS:
cd XSRCDIR
cvs -q update -PAd -I - | awk '$1=="?" {print $2}' | xargs rm -f
o How to build something with debug information?
----------------------------------------------
You can use "env CFLAGS=-g make -f Makefile.bsd-wrapper build" to
build any module with debugging information, but you'll need to remove
XOBJDIR/xorg-config.cache.${MACHINE} before doing that because
autoconf caches the value of CFLAGS in its cache.
o How to get a core file out of the X server?
-------------------------------------------
Several things are needed:
1) set kern.nosuidcoredump=2 in /etc/sysctl.conf
2) put
Option "NoTrapSignals" "true"
in the "ServerFlags" section of /etc/X11/xorg.conf. If such a section
doesn't exist, it can be added as follow:
Section "ServerFlags"
Option "NoTrapSignals" "true"
EndSection
anywhere in the configuration file.
3) start the X server as root, with the -keepPriv option. A regular
user is not allowed to use this option. If you use xdm, you can add
the option in /etc/X11/xdm/Xservers. If you want to use startx, you
need to run it as root, like this:
startx -- /usr/X11R6/bin/X -keepPriv
Now the X server will dump core when catching a fatal signal. But it
will also not be able to restore the text mode on exit. So be prepared
to log in remotely (serial terminal or ssh) to reboot your machine or
to restart X.
The core dump will be in /var/crash.
See also <http://xorg.freedesktop.org/wiki/Development/Documentation/ServerDebugging>
--
$OpenBSD: README,v 1.20 2007/07/14 11:20:10 jolan Exp $
