summaryrefslogtreecommitdiff
path: root/NewModuleGuidelines.mdwn
diff options
context:
space:
mode:
authorJoe Rayhawk <jrayhawk@freedesktop.org>2013-06-30 20:40:58 -0700
committerJoe Rayhawk <jrayhawk@freedesktop.org>2013-06-30 20:40:58 -0700
commit5cd4b8595804cd50e50e42ab2812dc1006d238d1 (patch)
treeb8019eb9a8f0eb8d52d6ff7e72a86e00e71cadf8 /NewModuleGuidelines.mdwn
parentedf2ddad7660d2c36116dd53a98f4b62fd5d9a92 (diff)
moin2mdwn: convert page NewModuleGuidelines
Diffstat (limited to 'NewModuleGuidelines.mdwn')
-rw-r--r--NewModuleGuidelines.mdwn368
1 files changed, 368 insertions, 0 deletions
diff --git a/NewModuleGuidelines.mdwn b/NewModuleGuidelines.mdwn
new file mode 100644
index 00000000..cbcd5e9a
--- /dev/null
+++ b/NewModuleGuidelines.mdwn
@@ -0,0 +1,368 @@
+
+
+## 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.
+
+[[!toc ]]
+
+
+## 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:
+
+* ChangeLog: list of changes automatically generated from git by Makefile.am
+* COPYING: the correct license for the package
+* INSTALL: standard instructions for the building and installing package, automatically generated
+* README: a brief description and appropriate URLs
+* autogen.sh: script that invokes Autotools to build and configure the package
+* configure.ac: Autoconf input file
+* Makefile.am: top level Automake input file (others will be added to each subdir within the component)
+* .gitignore: tells Git to ignore files that are not tracked in the package repository
+
+### 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 a fictitious configuration to illustrate the most common statements encountered in the configure.ac file.
+[[!format txt """
+# Initialize Autoconf
+AC_PREREQ([x.yy])
+AC_INIT([xsample], [1.0.1],
+ [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg], [xsample])
+AC_CONFIG_SRCDIR([Makefile.am])
+AC_CONFIG_MACRO_DIR([m4])
+AC_CONFIG_HEADERS([config.h])
+
+# Initialize Automake
+AM_INIT_AUTOMAKE([foreign dist-bzip2])
+AM_MAINTAINER_MODE
+
+# Initialize libtool
+AC_PROG_LIBTOOL
+
+# Require xorg-macros minimum of 1.10 for DocBook/XML
+m4_ifndef([XORG_MACROS_VERSION],
+ [m4_fatal([must install xorg-macros 1.10 or later before running autoconf/autogen])])
+XORG_MACROS_VERSION(1.10)
+XORG_DEFAULT_OPTIONS
+
+# Checks for programs.
+AC_PROG_LN_S
+
+# Obtain compiler/linker options for dependencies
+PKG_CHECK_MODULES(XPM, xproto x11)
+
+AC_CONFIG_FILES([Makefile
+ src/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. This can be found in the [[ModularDevelopersGuide#GNUBuildSystem|ModularDevelopersGuide]] wiki.
+
+**AC_INIT (package, version, [bug-report], [tarname])**
+
+Parameters:
+
+1. The package short descriptive name or the tar name which is often the source subdirectory.
+1. The package version number as advised by release management. See [[X.Org and XFree86 Version Numbering Schemes.|http://www.x.org/releases/X11R7.5/doc/Versions.html/]]
+1. Exactly this URL: [[https://bugs.freedesktop.org/enter_bug.cgi?product=xorg|https://bugs.freedesktop.org/enter_bug.cgi?product=xorg]]
+1. The name (lower case) of the tarball. If omitted, the default value is the first parameter, lower cased by Autoconf.
+**AC_CONFIG_SRCDIR([Makefile.am])**
+
+This statement tells Autoconf where the configuration is and provides a safety check when using --srcdir in case the directory does not exist. The filename supplied should be the one you are exists. Given all modules have Makefile.am, this filename is preferred so all modules have the same code.
+
+**AC_CONFIG_MACRO_DIR([m4])**
+
+Libtool recommends this statement and will store its macros there. Other Autotools may use this statement to find macros. If the module has created its own macros, they should be stored in git under the m4 directory. A common one is _AX_DEFINE_DIR_ from the [[Autoconf Archive.|http://www.gnu.org/software/autoconf-archive/]]
+
+Do not add `"ACLOCAL_AMFLAGS = -I m4"` in Makefile.am unless the module has a macro checked-in git. Aside from being useless, running the configuration will fail on a freshly cloned module as the m4 directory does not yet exists.
+
+**AC_CONFIG_HEADERS ([config.h])**
+
+This macro generates a config.h header file containing C preprocessor #define statements. Macros like AC_CHECK_HEADERS and AC_CHECK_FUNCS causes these #define statements to be created.
+
+Do not use the deprecated and undocumented _AC_CONFIG_HEADER_ (singular) version.
+
+**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_ for files that are usually distributed and that users should normally not have to update. The autogen.sh script enables them through --enable-maintainer-mode.
+
+**AC_PROG_LIBTOOL**
+
+This statement is not a program check as its name implies, it initializes the libtool library-building support services. It is sometimes preceded by `AC_DISABLE_STATIC` to prevent the creation of a static version of the library. In version 2 of libtool, this statement is more appropriately named `LT_INIT`.
+
+**AC_PROG_`XXX`**
+
+A number of program checks are performed to insure the desired program is available on the platform and invoked with the appropriate options. Most of the common tools such as `grep` and `sed` have already been checked by the compiler or by the various macros contained in `XORG_DEFAULT_OPTIONS`.
+
+**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.
+
+* XORG_CWARNFLAGS: platform adjusted compiler warning flags
+* XORG_STRICT_OPTION: additional warning flags
+* XORG_RELEASE_VERSION: defines variables for major, minor and patch level
+* XORG_CHANGELOG: contains a makefile rule which creates the ChangeLog file from Git
+* XORG_INSTALL: contains a makefile rule which provides the INSTALL file in the module root directory
+* XORG_MANPAGE_SECTIONS: platform adjusted man page section number
+The above macros invoke the following Autoconf macros:
+
+* AC_PROG_INSTALL
+* AC_PROG_CC_C99
+* AC_PROG_SED
+* AC_CANONICAL_HOST
+
+#### Makefile.am
+
+This is the minimum top level Makefile.am input file. It must contain targets to generate the ChangeLog and INSTALL files. It invokes the Makefile.am from the src subdirectory. The macro `XORG_DEFAULT_OPTIONS` is required in configure.ac.
+
+
+[[!format txt """
+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.
+
+
+[[!format txt """
+ 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
+
+"""]]
+
+#### A Warning About Autotools Warnings and Suggestions
+
+The version of the Autotools you are currently working with is most likely to be a lot more recent than the minimum version required by X.Org. This means your version contains features that are not available on earlier versions. Autoconf may issue warnings or make suggestions, but you should not implement them if they use features unavailable in the minimum version.
+
+One example is the silent rules feature from Automake 1.11 which is not available in 1.10. Because is was a popular feature, a backward compatibility workaround was introduced in util-macros which made this feature a noop on 1.10.
+
+
+### Guidelines for proto
+
+The proto module's directory structure is as follows:
+
+
+[[!format txt """
+ 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|ArchitectureWorkingGroup]] before changes are checked into the trunk.
+
+The basic structure of each component is as follows:
+
+* _extensionname_proto.h: protocol headers
+* _extensionname_proto.txt: description of protocol
+* _extensionname_proto.pc.in: pkg-config metadata file for use with the autotools (note that the core protocol metadata file will be named xproto.pc.in to be more descriptive and not conflict with xlib's metadata file)
+* specs: the protocol specifications when available in DocBook/XML format
+* plus the files listed in the general guidelines above
+
+### Guidelines for lib
+
+The lib module's directory structure is as follows:
+
+
+[[!format txt """
+ 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:
+
+* doc: any library documentation (e.g., howto's, specs, books, etc.)
+* include: the library's public headers, which are placed in a subdir corresponding to where they go in the system (e.g., the Xlib headers go in `include/X11`, and the Xv headers go in `include/X11/extensions`).
+* man: man pages for library
+* src: source code
+* specs: specification documents
+* doc: other documentation
+* _library-name_.pc.in: pkg-config metadata file for use with the autotools
+* plus the files listed in the general guidelines above
+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:
+
+
+[[!format txt """
+ 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:
+
+
+[[!format txt """
+ 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:
+
+* doc: any driver documentation (e.g., howto's, info files, etc.)
+* man: man pages for the driver
+* src: source code
+* util: special utilities used by the driver developers and/or users
+* plus the files listed in the general guidelines above
+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:
+
+
+[[!format txt """
+ 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:
+
+* doc: any application documentation (e.g., howto's, info files, etc.)
+* man: man pages for the app
+* src: source code for the app
+* plus the files listed in the general guidelines above
+
+### Guidelines for font
+
+The font module's directory structure is as follows:
+
+
+[[!format txt """
+ 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:
+
+
+[[!format txt """
+ 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:
+
+
+[[!format txt """
+ 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`).