Annotation of xenocara/README, Revision 1.45
1.1 matthieu 1:
2: Notes on building Xenocara for OpenBSD X hackers
3:
4: This document presents some techniques that can be useful for people
5: wanting to hack the xenocara tree. It assumes some basic knowledge of
6: the OpenBSD build system, as described in the release(8) manual page.
7:
8: o About Xenocara
9: --------------
1.11 david 10: Xenocara is the name chosen for OpenBSD's version of X. It's
1.29 matthieu 11: currently based on X.Org 7.7 and its dependencies. The goal of
1.1 matthieu 12: Xenocara is to provide a framework to host local modifications and to
13: automate the build of the modular X.Org components, including 3rd
1.11 david 14: party packages and some software maintained by OpenBSD developers.
1.1 matthieu 15:
16: o Source tree
17: -----------
18:
19: The organisation of the xenocara directory follows the general
20: organisation used in X.Org:
21:
22: - app: X applications and utilities
23: - data: various data files (keyboard mappings and bitmaps)
24: - doc: documentation
25: - driver: input and video drivers
26: - font: fonts
27: - lib: libraries
28: - proto: X protocol headers
29: - util: utilities that don't fit anywhere else
1.24 matthieu 30: - xserver: the source for the X servers
1.1 matthieu 31:
32: In addition Xenocara uses the following directories:
33:
1.28 matthieu 34: - dist: contains some of the 3rd party sources, when keeping them
1.44 sthen 35: separate helps the build system (fontconfig, xcb and
1.36 matthieu 36: xkeyboard-config)
1.1 matthieu 37: - distrib: all binary distribution related tools and data
1.36 matthieu 38: - etc: some default config files
1.3 matthieu 39: - share: make(1) configuration for Xenocara
1.1 matthieu 40:
1.2 matthieu 41: At the top-level directory two files describe the individual
1.3 matthieu 42: components of Xenocara:
1.1 matthieu 43:
1.2 matthieu 44: - MODULES lists all X.Org components (imported from the X.Org
45: distribution at http://xorg.freedesktop.org/archive/)
1.3 matthieu 46: - 3RDPARTY lists all 3rd party software components provided in Xenocara,
1.2 matthieu 47: either as dependencies of the X.Org software, or as
48: complements to it to provide a more useable default
49: environment.
50:
51: o Compiling and installing
52: ------------------------
53:
1.25 matthieu 54: Xenocara is made up of almost three hundred different independent
55: packages that need to be built and installed in the right order,
56: especially while bootstrapping (while /usr/X11R6 is still empty). The
57: Xenocara Makefiles take care of that using the 'build' target.
1.2 matthieu 58:
1.5 matthieu 59: Quick startup guide
60:
61: The following steps will build and install everything for the first time.
62:
1.37 matthieu 63: cd /usr/xenocara
64: doas make bootstrap
1.41 matthieu 65: doas make obj
1.37 matthieu 66: doas make build
1.5 matthieu 67:
68: If you want to use another obj directory see below.
69:
1.2 matthieu 70: Requirements
71:
72: A freshly checked out xenocara tree is buildable without any external
1.23 matthieu 73: tool. Only the xenocara and the src (currently only the
1.24 matthieu 74: src/sys/dev/pci/pcidevs file) trees are needed.
1.23 matthieu 75:
76: However if you start modifying things in the automake build
1.2 matthieu 77: system used by many packages, you will need to have the following
1.3 matthieu 78: GNU autotools packages installed:
1.2 matthieu 79:
1.31 matthieu 80: - automake 1.12 (devel/automake/1.12)
81: - autoconf 2.69 (devel/autoconf/2.69)
1.30 matthieu 82: - metaauto 0.9 (or later) (devel/metaauto)
1.28 matthieu 83: - libtool 2.4.2 (or later) (devel/libtool)
1.2 matthieu 84:
1.17 matthieu 85: If you have your source tree on an NFS partition, make sure the clock
1.23 matthieu 86: of your server and client are properly synchronised. Any significant
87: drift will cause various problems during builds.
1.17 matthieu 88:
1.8 matthieu 89: Path
90:
1.24 matthieu 91: To build Xenocara, you need to have /usr/X11R6/bin in your PATH.
1.8 matthieu 92:
1.3 matthieu 93: If you have installed the full Xenocara X sets on your system, you
94: don't need to build all of Xenocara to patch one element. You can go
1.24 matthieu 95: to any module sub-directory and run 'make build' from there.
1.2 matthieu 96:
1.8 matthieu 97: Source directory
98:
99: The variable XSRCDIR can be set either in the environment or in
1.9 matthieu 100: /etc/mk.conf to point to the xenocara source tree, in case you keep it
1.21 matthieu 101: in a non-standard directory (the default is /usr/xenocara).
1.8 matthieu 102:
1.2 matthieu 103: Objdirs
104:
1.41 matthieu 105: Xenocara requires objdirs. Just run 'make obj' as root at any level
106: before 'make build' to make sure that the object directories are
107: created. XOBJDIR defines the obj directory that is used (defaults to
108: /usr/xobj). It should be created before running 'make obj'.
1.2 matthieu 109:
110: o Regenerating configure scripts
111: ------------------------------
112:
113: Whenever you touched an import file for GNU autotools (Makefile.am,
114: configure.ac mostly), you need to rebuild the configure script and
1.24 matthieu 115: makefiles skeletons. For that use the following command in the
1.14 matthieu 116: directory where you edited the autotools source files:
1.2 matthieu 117:
1.39 jsg 118: make -f Makefile.bsd-wrapper autoreconf
1.38 matthieu 119: doas make -f Makefile.bsd-wrapper build
1.2 matthieu 120:
1.15 matthieu 121: o Cleaning in packages managed by autotools
122: -----------------------------------------
123:
124: One common problem when building xenocara is the case where the obj
125: directory didn't exist (or the symbolic link pointed to a non-existent
1.24 matthieu 126: directory) when the source was first built. After fixing this problem,
127: 'configure' will refuse to work in the obj dir, because the source
128: is already configured.
1.15 matthieu 129:
130: To recover from this in one package:
131:
132: rm -f obj
133: make -f Makefile.bsd-wrapper cleandir
134: mkdir XOBJDIR
135: make -f Makefile.bsd-wrapper obj
1.37 matthieu 136: doas make -f Makefile.bsd-wrapper build
1.15 matthieu 137:
138: or from the root of the xenocara tree:
139:
1.24 matthieu 140: find . -type l -name obj | xargs rm -f
1.15 matthieu 141: make cleandir
142: mkdir XOBJDIR
143: make obj
1.37 matthieu 144: doas make build
1.15 matthieu 145:
1.16 matthieu 146: for more desperate cases, remove all files from XSRCDIR not in CVS:
1.15 matthieu 147:
148: cd XSRCDIR
149: cvs -q update -PAd -I - | awk '$1=="?" {print $2}' | xargs rm -f
150:
1.42 matthieu 151: o Updating XCB to a new release
152: -----------------------------
153:
154: libxcb uses C source files that are generated from the XML protocol
155: specification using xcbgen, written in Python. On OpenBSD those files
156: cannot be generated during a normal 'make build' since Python is not
157: in the base system. So the generated version are checked in CVS
158: (in lib/libxcb/src/). Here is the receipt to update them when updating
159: to a new release of XCB:
160:
161: 1) Update proto/xcb-proto.
162: 2) Update the x11/py-xcbgen port to the same version and install the
1.43 matthieu 163: python3 package.
1.42 matthieu 164: 3) Update dist/libxcb.
165: 4) Check lib/libxcb/src/Makefile if new files need to be generated.
166: 5) Run 'make' in lib/xcb/src to generate the files for the new version.
167: 6) Check lib/libxcb/ for other files needing updates.
168: 7) Commit the result.
169:
1.19 matthieu 170: o How to build something with debug information?
171: ----------------------------------------------
172:
173: You can use "env CFLAGS=-g make -f Makefile.bsd-wrapper build" to
174: build any module with debugging information, but you'll need to remove
175: XOBJDIR/xorg-config.cache.${MACHINE} before doing that because
176: autoconf caches the value of CFLAGS in its cache.
177:
178: o How to get a core file out of the X server?
179: -------------------------------------------
180:
181: Several things are needed:
182:
183: 1) set kern.nosuidcoredump=2 in /etc/sysctl.conf
1.24 matthieu 184: 2) put
1.19 matthieu 185:
186: Option "NoTrapSignals" "true"
187:
1.24 matthieu 188: in the "ServerFlags" section of /etc/X11/xorg.conf. If such a section
1.19 matthieu 189: doesn't exist, it can be added as follow:
190:
191: Section "ServerFlags"
192: Option "NoTrapSignals" "true"
193: EndSection
194:
1.24 matthieu 195: anywhere in the configuration file.
1.19 matthieu 196:
197: 3) start the X server as root, with the -keepPriv option. A regular
1.40 matthieu 198: user is not allowed to use this option. If you use xenodm, you can
199: add the option in /etc/X11/xenodm/Xservers. If you want to use
200: startx, you need to run it as root, like this:
1.19 matthieu 201:
202: startx -- /usr/X11R6/bin/X -keepPriv
203:
204: Now the X server will dump core when catching a fatal signal. But it
205: will also not be able to restore the text mode on exit. So be prepared
206: to log in remotely (serial terminal or ssh) to reboot your machine or
207: to restart X.
208:
209: The core dump will be in /var/crash.
210:
211: See also <http://xorg.freedesktop.org/wiki/Development/Documentation/ServerDebugging>
212:
1.45 ! tb 213: --
! 214: $OpenBSD: README,v 1.44 2021/07/14 18:46:21 sthen Exp $
![[BACK]](/icons/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / xenocara