Anatomy of a Language Front End#

A front end for a language in GCC has the following parts:

A directory language under gcc containing source files for that front end. See The Front End language Directory, for details.
A mention of the language in the list of supported languages in gcc/doc/install.texi.
A mention of the name under which the language’s runtime library is recognized by --enable-shared=package in the documentation of that option in gcc/doc/install.texi.
A mention of any special prerequisites for building the front end in the documentation of prerequisites in gcc/doc/install.texi.
Details of contributors to that front end in gcc/doc/contrib.texi. If the details are in that front end’s own manual then there should be a link to that manual’s list in contrib.texi.
Information about support for that language in gcc/doc/frontends.texi.
Information about standards for that language, and the front end’s support for them, in gcc/doc/standards.texi. This may be a link to such information in the front end’s own manual.
Details of source file suffixes for that language and -x lang options supported, in gcc/doc/invoke.texi.
Entries in default_compilers in gcc.cc for source file suffixes for that language.
Preferably testsuites, which may be under gcc/testsuite or runtime library directories.

Todo

document somewhere how to write testsuite harnesses
Probably a runtime library for the language, outside the gcc directory.

Todo

document this further
Details of the directories of any runtime libraries in gcc/doc/sourcebuild.texi.
Check targets in Makefile.def for the top-level Makefile to check just the compiler or the compiler and runtime library for the language.

If the front end is added to the official GCC source repository, the following are also necessary:

At least one Bugzilla component for bugs in that front end and runtime libraries. This category needs to be added to the Bugzilla database.
Normally, one or more maintainers of that front end listed in MAINTAINERS.
Mentions on the GCC web site in index.html and frontends.html, with any relevant links on readings.html. (Front ends that are not an official part of GCC may also be listed on frontends.html, with relevant links.)
A news item on index.html, and possibly an announcement on the gcc-announce@gcc.gnu.org mailing list.
The front end’s manuals should be mentioned in maintainer-scripts/update_web_docs_git (see Building Documentation) and the online manuals should be linked to from onlinedocs/index.html.
Any old releases or CVS repositories of the front end, before its inclusion in GCC, should be made available on the GCC web site at https://gcc.gnu.org/pub/gcc/old-releases/.
The release and snapshot script maintainer-scripts/gcc_release should be updated to generate appropriate tarballs for this front end.
If this front end includes its own version files that include the current date, maintainer-scripts/update_version should be updated accordingly.

The Front End language Directory#

A front end language directory contains the source files of that front end (but not of any runtime libraries, which should be outside the gcc directory). This includes documentation, and possibly some subsidiary programs built alongside the front end. Certain files are special and other parts of the compiler depend on their names:

config-lang.in: This file is required in all language subdirectories. See The Front End config-lang.in File, for details of its contents
Make-lang.in: This file is required in all language subdirectories. See The Front End Make-lang.in File, for details of its contents.
lang.opt: This file registers the set of switches that the front end accepts on the command line, and their --help text. See Option specification files.
lang-specs.h: This file provides entries for default_compilers in gcc.cc which override the default of giving an error that a compiler for that language is not installed.
language-tree.def: This file, which need not exist, defines any language-specific tree codes.

The Front End config-lang.in File#

Each language subdirectory contains a config-lang.in file. This file is a shell script that may define some variables describing the language:

language: This definition must be present, and gives the name of the language for some purposes such as arguments to --enable-languages.
lang_requires: If defined, this variable lists (space-separated) language front ends other than C that this front end requires to be enabled (with the names given being their language settings). For example, the Obj-C++ front end depends on the C++ and ObjC front ends, so sets lang_requires="objc c++".
subdir_requires: If defined, this variable lists (space-separated) front end directories other than C that this front end requires to be present. For example, the Objective-C++ front end uses source files from the C++ and Objective-C front ends, so sets subdir_requires="cp objc".
target_libs: If defined, this variable lists (space-separated) targets in the top level Makefile to build the runtime libraries for this language, such as target-libobjc.
lang_dirs: If defined, this variable lists (space-separated) top level directories (parallel to gcc), apart from the runtime libraries, that should not be configured if this front end is not built.
build_by_default: If defined to no, this language front end is not built unless enabled in a --enable-languages argument. Otherwise, front ends are built by default, subject to any special logic in configure.ac (as is present to disable the Ada front end if the Ada compiler is not already installed).
boot_language: If defined to yes, this front end is built in stage1 of the bootstrap. This is only relevant to front ends written in their own languages.
compilers: If defined, a space-separated list of compiler executables that will be run by the driver. The names here will each end with \$(exeext).
outputs: If defined, a space-separated list of files that should be generated by configure substituting values in them. This mechanism can be used to create a file language/Makefile from language/Makefile.in, but this is deprecated, building everything from the single gcc/Makefile is preferred.
gtfiles: If defined, a space-separated list of files that should be scanned by gengtype.cc to generate the garbage collection tables and routines for this language. This excludes the files that are common to all front ends. See Memory Management and Type Information.

The Front End Make-lang.in File#

Each language subdirectory contains a Make-lang.in file. It contains targets lang.hook (where lang is the setting of language in config-lang.in) for the following values of hook, and any other Makefile rules required to build those targets (which may if necessary use other Makefiles specified in outputs in config-lang.in, although this is deprecated). It also adds any testsuite targets that can use the standard rule in gcc/Makefile.in to the variable lang_checks.

all.cross start.encap rest.encap

Todo

exactly what goes in each of these targets?

tags

Build an etags TAGS file in the language subdirectory in the source tree.

info

Build info documentation for the front end, in the build directory. This target is only called by make bootstrap if a suitable version of sphinx is available, so does not need to check for this, and should fail if an error occurs.

pdf

Build PDF documentation for the front end, in the build directory.

html

Build HTML documentation for the front end, in the build directory.

man

Build generated man pages for the front end from reStructuredText format (see Building Documentation), in the build directory. This target is only called if the necessary tools are available, but should ignore errors so as not to stop the build if errors occur; man pages are optional and the tools involved may be installed in a broken way.

install-common

Install everything that is part of the front end, apart from the compiler executables listed in compilers in config-lang.in.

install-info

Install info documentation for the front end, if it is present in the source directory. This target should have dependencies on info files that should be installed.

install-man

Install man pages for the front end. This target should ignore errors.

install-plugin

Install headers needed for plugins.

srcextra

Copies its dependencies into the source directory. This generally should be used for generated files such as Bison output files which are not version-controlled, but should be included in any release tarballs. This target will be executed during a bootstrap if --enable-generated-files-in-srcdir was specified as a configure option.

srcinfo srcman

Copies its dependencies into the source directory. These targets will be executed during a bootstrap if --enable-generated-files-in-srcdir was specified as a configure option.

uninstall

Uninstall files installed by installing the compiler. This is currently documented not to be supported, so the hook need not do anything.

mostlyclean clean distclean maintainer-clean

The language parts of the standard GNU *clean targets. For GCC, maintainer-clean should delete all generated files in the source directory that are not version-controlled, but should not delete anything that is.

Make-lang.in must also define a variable lang_OBJS to a list of host object files that are used by that language.