NewModuleGuidelines

New Module Guidelines

This text was written for developers converting to modular structure during the 7.0 bootstrap. It may still be useful to people adding new modules to the tree.

Contents

  1. New Module Guidelines
  2. Guidelines for module components
    1. General guidelines for all module components
    2. Configuration files content guidelines
      1. configure.ac
      2. Makefile.am
      3. autogen.sh
      4. .gitignore
      5. README
    3. Guidelines for proto
    4. Guidelines for lib
    5. Guidelines for server
    6. Guidelines for driver
    7. Guidelines for app
    8. Guidelines for font
    9. Guidelines for doc
    10. Guidelines for util
  3. Converting code from Imake to Autotools
    1. Autotool replacements for common Imake variables/macros

Guidelines for module components

It is impossible to pre-specify all possible structures for every module component, so guidelines are given and should be followed whenever possible. In the next section, general guidelines are given for what should be included in all module components, general style, etc. Following that section are guidelines for the basic structure of each module and their module components.

General guidelines for all module components

All module components should have the following files:

Configuration files content guidelines

The GNU Build System is composed of user hand written input files (e.g. configure.ac, Makefile.am) from which output files (e.g. configure, Makefile.in, Makefile, etc...) are generated. The former are checked-in the source tree while the latter are not. For a complete list of generated files, refer to the defaults section in the .gitignore file.

NOTE: All X.Org modules are currently being revisited to follow these guidelines.

configure.ac

This is the minimum configuration all xorg modules must have in order to benefit from all the facilities provided by the build infrastructure. 

AC_PREREQ([x.yy])
AC_INIT([X Sample Module],
        [1.0.0],
        [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg],
        [xsample])
AC_CONFIG_SRCDIR([Makefile.am])
AC_CANONICAL_HOST
AM_INIT_AUTOMAKE([foreign dist-bzip2])
AM_MAINTAINER_MODE

# Require xorg-macros: XORG_DEFAULT_OPTIONS
m4_ifndef([XORG_MACROS_VERSION], 
          [m4_fatal([must install xorg-macros 1.3 or later before running autoconf/autogen])])
XORG_MACROS_VERSION(1.3)
XORG_DEFAULT_OPTIONS

# Checks for programs.
AC_PROG_CC
AC_PROG_CC_C99
AC_PROG_INSTALL

AC_CONFIG_FILES([Makefile])
AC_OUTPUT

An explanation of some of the statements:

AC_PREREQ([x.yy])

This will prevent a version older than x.yy of Autoconf to create the package configuration. It is set to the minimum version at which all X.Org modules will configure correctly. It can be found in the Required Tools section in the ModularDevelopersGuide wiki.

AC_INIT (package, version, [bug-report], [tarname])

Parameters:

  1. The package short descriptive name rather than the tar name or build directory.
  2. The package version number as advised by release management

  3. Exactly this URL: https://bugs.freedesktop.org/enter_bug.cgi?product=xorg

  4. The name (lowercase) of the tarball

AC_CONFIG_SRCDIR([Makefile.am])

This statement provides a safety check when using --srcdir in case the directory does not exist.

AC_CANONICAL_HOST

This statement is required by XORG_DEFAULT_OPTIONS for the man page sections. It compute the canonical host-system type variable, host, and its three individual parts host_cpu, host_vendor, and host_os.

AM_INIT_AUTOMAKE([foreign dist-bzip2])

The foreign Automake option defines the strictness level. Xorg is not a GNU project, so their rules will not be enforced. The dist-bzip2 option causes Automake to generate both a GNU zip and bzip2 compressed archive.

AM_MAINTAINER_MODE

This disables the maintainer build rules when building from a tarball to prevent the deletion of files that cannot be regenerated. See autogen.sh below.

AC_CONFIG_HEADERS (name-of-config-file.h ..., [cmds], [init-cmds])

This statement should be used wherever possible to assist the developer. Note that the config header should be named something unique to that package and should never be installed. It should also be added to .gitignore.

When testing for features with #ifdef statements in the code you should generally have a matching configure option.

XORG_DEFAULT_OPTIONS

This macro expands into several macros and provide several build functions. Refer to the module generated aclocal.m4 file as this is subject to change.

AC_PROG_XXX

A number of program checks are performed to insure the building platform meets the requirements. These are required by the various macros contained in XORG_DEFAULT_OPTIONS.

Makefile.am

This is the minimum top level Makefile.am input file. It must contain targets to generated the ChangeLog and INSTALL files. It invokes the Makefile.am from the src subdirectory. The macro XORG_DEFAULT_OPTIONS is required in configure.ac. 

SUBDIRS = src

.PHONY: ChangeLog INSTALL
INSTALL:
        $(INSTALL_CMD)
ChangeLog:
        $(CHANGELOG_CMD)

dist-hook: ChangeLog INSTALL

autogen.sh

It's role is to initiate the build of the package without the knowledge of the Autotools commands and options. It enables the maintainer build rules in the package that are otherwise turned off by default.

.gitignore

The .gitignore is part of the Git source code repository. It's role is to tell Git which file patterns to ignore (e.g *.o). Xorg has created a template with a defaults section which covers all generated files by the Autotools, complier, linker, lex, yacc, etc... Those generated file names will be ignored in all the subdirectories as well.

What is left for you to do is to add file names or name patterns at the bottom of the file that are specific to your modules. You can have a .gitignore in subdirectories as well.

README

The README file should contain, at a minimum, the package short descriptive name, a brief description and the X.Org project URLs. 

                                X Sample Module

This module provides a sample for the creation and maintenance of an X Window System module.

All questions regarding this software should be directed at the
Xorg mailing list:

        http://lists.freedesktop.org/mailman/listinfo/xorg

Please submit bug reports to the Xorg bugzilla:

        https://bugs.freedesktop.org/enter_bug.cgi?product=xorg

The master development code repository can be found at:

        git://anongit.freedesktop.org/git/xorg/sample/module

        http://cgit.freedesktop.org/xorg/sample/module

For patch submission instructions, see:

        http://www.x.org/wiki/Development/Documentation/SubmittingPatches

For more information on the git code manager, see:

        http://wiki.x.org/wiki/GitPage

Guidelines for proto

The proto module's directory structure is as follows: 

  proto/x11proto
  proto/compositeproto
  proto/damageproto
  proto/dmxproto
  proto/evieproto
  proto/fixesproto
  ...

Core protocol headers and protocol docs are in the X11 component. Extension protocol headers and protocol docs are put into a component named the same as the extension.

Please note that all changes to the protocol of one of the official X.Org Foundation components must be discussed with the Architecture Working Group before changes are checked into the trunk.

The basic structure of each component is as follows:

Guidelines for lib

The lib module's directory structure is as follows: 

  lib/libX11
  lib/libXt
  lib/libXcomposite
  lib/libICE
  lib/libSM
  lib/libdmx
  ...

Some libraries will have corresponding protocol headers that are kept in the proto module, while others will be standalone libraries.

The basic structure of each component should be:

Note that some libraries do not have any documentation or man pages, so those subdirs should not be created until they are needed.

Guidelines for server

The server module's directory structure is as follows: 

  xserver/dix
  xserver/hw
  xserver/mi
  xserver/os
  xserver/mi
  xserver/Xext
  ...

Within the xserver module, the structure is the same as found in the monolithic tree in xc/programs/Xserver except that the drivers are not included in this module. Instead, the drivers have been moved to the driver module (see below).

Guidelines for driver

The driver module's directory structure is as follows: 

  driver/xf86-video-ati
  driver/xf86-video-mga
  driver/xf86-video-i810
  driver/xf86-input-mouse
  driver/xf86-input-keyboard
  driver/xf86-input-spaceorb
  ...

The name of each component is created from the DDX, driver interface, and device(s) that it supports. Currently, there is one DDX (xf86) and two driver interfaces (video and input). As other driver interfaces are developed, they should be added to the list above.

The basic structure of each component should be:

Note that some drivers do not have any docs, man pages or utilities, so those subdirs should not be created until they are needed. Also, other directories may be necessary that contain code for examples, config tools, etc.

Guidelines for app

The app module's directory structure is as follows: 

  app/xdpyinfo
  app/xwd
  app/xwud
  app/twm
  ...

The name of most components will be the application name, but when not, it should be descriptive of the component contents.

Note that it is very difficult to specify a structure for all apps since they vary greatly in complexity and organization, but when no other structure is already available, the one below could be adopted:

Guidelines for font

The font module's directory structure is as follows: 

  font/util
  font/adobe-100dpi
  font/adobe-utopia-100dpi
  font/bitstream-type1
  ...

The fonts are modularized along foundry and type boundaries, where type is 100dpi, 75dpi, misc, cyrillic, type1, ttf, etc., and the font module components are named foundary-type. Note that some fonts have special licenses and should be put into separate components. These separate components should be listed by foundary-family*-type. For example, most of the adobe foundry fonts have the same license with the exception of the utopia family fonts, so for the 100dpi adobe fonts, the ones that share the same license are placed in the adobe-100dpi component and the utopia fonts are placed in the adobe-utopia-100dpi component.

Note that the license for the fonts in each component should be reflected in the COPYING file.

Guidelines for doc

The doc module's directory structure is as follows: 

  doc/xorg-docs
  doc/xorg-sgml-doctools

A special case is the documentation that has not yet been converted to a modern format, which will be kept in the doc module until they are converted. At present, these are contained within the xorg-docs component.

Guidelines for util

The util module's directory structure is as follows: 

  util/macros
  util/modular
  util/cf
  util/gccmakedep
  util/imake
  util/lndir
  util/makedepend

This module contains the build tools for the modular tree as well as the build tools and configuration files that were used in the monolithic tree. These are kept around for legacy applications that have not yet been converted to use autotools.

The build tools for the modular tree are contained in the modular component, and the m4 macros used across the entire modular build are contained in the macros component. Important: note that when changes are made to the m4 macros, all of the packages in the modular tree that use the macros that you changed are affected, and those packages will need to be rebuilt, have their version numbers bumped and released during the next release cycle.

Many of the common utilities that are used mainly with imake are contained in the imake component. Others that have uses outside of imake are in their own component directories (e.g., gccmakedep, lndir and makedepend).

Converting code from Imake to Autotools

As standards and useful techniques are developed to assist others in converting their packages from imake to the autotools, they will be added to this section.

Autotool replacements for common Imake variables/macros