Firebird Documentation Index → Getting and building the Firebird documentation

1. Introduction: Purpose of this Howto — Intended audience

This Howto explains, step by step, how you can download and build the firebird-documentation repository from the Firebird Project.

1.1. What is this "firebird-documentation repository" anyway?

The firebird-documentation repository is part of the Firebird Project on GitHub: https://github.com/FirebirdSQL/firebird-documentation. It is a collective effort, aimed at producing comprehensive and accurate documentation on the Firebird RDBMS (Relational Database Management System).

It is important to understand that the firebird-documentation repository contains the documentation in source form — to be more precise: in AsciiDoc and — for some older documentation — DocBook XML format. These sources need to be processed (built) to obtain easily readable docs, which can then be published on the Internet.

1.2. Apart from the firebird-documentation repository, is there any other Firebird documentation?

Yes! Some useful Firebird documentation has been produced outside the firebird-documentation repository. We still have a long way to go before the documentation in the firebird-documentation repository will be anywhere near complete. In fact, one of the reasons this Howto is written is that it can help would-be docwriters to overcome their first hurdles.

If you are looking for ready Firebird documentation and lots of it, your best starting places are:

1.3. Do I really have to build the docs myself? Isn’t there an easier way?

Sure there’s an easier way. As soon as a piece of documentation reaches a certain level of maturity, it is published — in PDF and HTML — on the Firebird website. You can find all the docs we have published via the Firebird Documentation Index.

You should download the firebird-documentation repository and build the docs yourself if and only if:

  • You want to check on the absolute latest state of the docs. (Be aware though that one of the reasons a version has not yet been published may be that it contains errors.)

  • You want to help write documentation yourself.

  • You’re interested in learning how this doc building stuff works, and/or you think DIY is more fun than an easy file download.

If one of the above applies to your situation, this Howto is for you.

2. Getting the firebird-documentation repository from GitHub

The firebird-documentation repository is a repository on the Firebird Project on GitHub. In order to download it, you need a piece of software called a git client. This section describes the necessary steps to get the software and the firebird-documentation repository. The actual doc building will be discussed in the next main section: Building the Firebird docs with Gradle.

2.1. What is git?

Git is a distributed version control system. It is a tool to manage software development, useful both for single developers and for teamwork. The Firebird Project on GitHub is divided into several so-called repositories, the firebird-documentation repository being one of them.

2.2. Git clients

Downloading a repository from GitHub is called cloning a repository in git lingo. To do that, you need a git client; they exist for practically every operating system. Here’s a list of git clients for some popular OSes:

  • Linux, BSD and other Unices

    • Command-line git is often pre-installed. If it isn’t, use the admin tools of your distribution to install it — you’ll typically find it in the development category (in ubuntu/debian you can install it from terminal with apt-get install git). If that doesn’t work for you, get it at https://git-scm.com/

  • Windows

  • Mac OS X

    • Mac OS X comes with command-line git already included.

  • Others

Get one or more of the aforementioned clients and install according to the instructions that come with it. After that, you are ready to check out the firebird-documentation repository.

2.3. Checking out the firebird-documentation repository

If you only want to build the documentation, you can clone the repository to your local machine and build from there. If you want to contribute, there are two ways of contributing to a repository: contributing through a pull request from a fork of the repository, or working directly on the repository.

The common method of contributing on GitHub is through so-called pull request. With a pull request, you don’t commit directly to the original repository. Instead, you fork the repository to your own GitHub account, make your changes on this fork, and then create a pull request to ask for those changes to be incorporated in the repository of the Firebird Project.

Working directly on the repository is similar to using a fork. The main difference is that working directly on the repository is more suitable for trusted regular contributors, while pull requests are very suitable for occasional or one-off contributions. To be able to work directly on the repository requires that you have been given commit-access to the repository, while anyone can create a pull request.

If you are unfamiliar with git and GitHub, you may also want to read Getting started with GitHub.

2.3.1. Cloning the firebird-documentation repository

To clone the Firebird repository on the command line:

If you decide to contribute through pull requests, replace the repository URL with the one from your fork.

Cloning through a git (graphical) client usually only requires the repository URL. Check the documentation of your client for more information.

3. Building the Firebird docs with Gradle

Several Java tools are used to produce the HTML and PDF docs from the AsciiDoc source. Therefore, you need a recent version of Java installed on your system.

In the next subsections we will show you:

  1. Where to get Java

  2. How to set up the environment for the build

  3. Building the HTML and PDF docs

If you already have recent version of Java installed, you may skip the first step.

3.1. Where to get Java

Download and install:

3.2. How to set up the environment for the build

The build scripts need an environment variable JAVA_HOME pointing to the Java install directory.

  • On Windows, this is typically something of the form C:\Program Files\Java\jdk-17.0.x. To be sure, check if there’s a directory called bin underneath it, and if this bin subdir contains the file java.exe.

    The path might be different if a different Java vendor than Oracle is used.

  • On Linux, it may be /usr/lib/java/jre or /usr/java/jdk, or…​ well, it can be a lot of things. The same check applies: it should have a subdir bin containing an executable file java (without the .exe extension here).

If you’re lucky, the JAVA_HOME environment variable is already present and correct. If not, you have to set it yourself, e.g. under Windows with set JAVA_HOME=C:\Program Files\Java\jdk-17.0.x` or under Linux/bash with export JAVA_HOME=/usr/lib/java/jdk. (Note: these paths are just examples; they may or may not be the same as yours.)

Tip: make the JAVA_HOME environment variable permanent, so you won’t have to set it again and again. How to do this depends on your OS. Consult its documentation if necessary.

3.3. Building the HTML and PDF docs

If you’ve made it here in one piece, you are finally ready to build the Firebird docs. Here’s what to do:

  1. If you haven’t done so already, this is the moment to read the README.md file that lives in the firebird-documentation directory. It may contain important information not (yet) included in this Howto.

  2. If you are in a graphical environment, open a command window.

  3. Unless the README.md instructs you otherwise, go to the folder firebird-documentation/ and give the command

    .\gradlew (in Windows), or

    ./gradlew (in Linux; works on Windows too)

    If everything was set up correctly, you now get a number of output lines ending with BUILD SUCCESSFUL, and mentioning some build targets (things you can build).

  4. Now you can build something more substantial, e.g. to build the AsciiDoc documentation:

    ./gradlew asciidocHtml

    or

    ./gradlew asciidocPdf

    Whatever you build will wind up in the directory tree under firebird-documentation/build

We have migrated actively maintained documentation to AsciiDoc. However, some older documentation — like release notes for older versions — have not been migrated.

It is no longer possible to build the old DocBook XML documentation. See 2026-01: Remove DocBook 4 Build Code for more information.

If you feel the need to modify and build DocBook documentation, take it as a sign that they need to be migrated to AsciiDoc. Contact us on firebird-devel to see what needs to be done.

By default, all documentation in the firebirddocs base set will be built. To specify a specific document or subset, see Building subsets with --docId. To specify a different base set, see Building a different base set with --baseName.

3.3.1. Building non-English sets with --language

To build documentation sets in non-English languages (in so far as they are available) use the --language argument and supply the language code, e.g.:

./gradlew asciidocPdf --language=es

Output will go into subdirectories like build/docs/asciidoc/pdf/es/firebirddocs, build/docs/asciidoc/pdf/fr/firebirddocs, etc

If you don’t specify --language, the English set will be built.

Not all language sets contain the same amount of documentation. This depends on docwriters' and translators' activity. Usually, the English set will be the most complete and the most up-to-date.

3.3.2. Building subsets with --docId

The examples given so far all produce the entire docset (for one language). Usually, this is not what you want. To build a specific document — e.g. a book or article — use the --docId argument.

Supply the directory name containing the document as argument of the --docId, for example for this document use:

./gradlew asciidocPdf --docId=docbuildhowto

You can find the ID by looking at the directory structure. Sources for individual books or articles are in a specific directory. The name of that directory is the ID of the document. For example, the sources of this document are in src/docs/asciidoc/en/firebirddocs/docbuildhowto/, so the ID is docbuildhowto

3.3.3. Building a different base set with --baseName

The Firebird Release Notes are part of the firebird-documentation repository, but they constitute a base set of their own, parallel to the default “firebirddocs” set. This has given rise to yet another command-line parameter, --baseName, whose value should be “rlsnotes” to build the Release Notes:

./gradlew asciidocPdf --baseName=rlsnotes

./gradlew asciidocPdf --baseName=rlsnotes --docId=rlsnotes50

./gradlew asciidocPdf --baseName=rlsnotes --language=fr

Another base set is refdocs, for reference manuals like the “Firebird Language Reference”.

3.3.4. Building the docs — conclusion

That’s it — you are now a certified Firebird doc builder. Congratulations!

If you want to write or translate docs for the Firebird Project yourself, also read the Firebird Docwriting Guide.

4. Keeping your firebird-documentation repository up to date

The firebird-documentation repository is a work in progress. Contributors commit changes to it on a regular basis. Some time after your initial checkout, your local copy will be out of sync with the repository at GitHub. Of course, it would be a waste of bandwidth if you had to check out the entire repository time and again, only to update those few files that have changed. Moreover, doing so would overwrite any changes you may have made yourself. That’s why git has an pull command. With pull, only the changes are downloaded from the server, and your own local changes are preserved. (In the event that another contributor has changed a file in the same spot as you, a conflict is signaled, and you must edit the file in question to solve it.)

Updating is easy. If you use command line git, go to the firebird-documentation directory and type:

git pull

This command is the same whether you checked out anonymously or with your GitHub account. Git knows which server to contact and how to authenticate you because this information is saved in the firebird-documentation/.git subdirectory, which was created automatically when you first checked out the repository.

If you use another git tool, look for its pull command or menu option.

Be aware that git offers multiple ways to update, including fetching and merging changes.

4.1. Keeping a fork up-to-date

If you are working on a fork of the repository, updating requires a bit more preparation. Your local clone of a git repository can be associated with multiple remote repositories. By default, the repository you cloned from is called the origin. You can associate multiple remote repositories (or remote) with your clone.

To add the firebird-documentation repository as a remote with the name upstream to your repository, you can use:

git remote add upstream https://github.com/FirebirdSQL/firebird-documentation.git

The name upstream is a common name for pointing to the original repository you forked.

Then to update your fork with the changes from the remote repository, you can use:

git fetch upstream
git rebase upstream/master

(Instead of rebase you can also use merge, but we prefer rebase.)

If you use a fork, it is best to leave master pristine (do not commit your own changes there, only sync it with upstream), and instead work in branches for different units of work. This makes it easier and cleaner to create pull requests.

See Fork a repo on GitHub for more information.

5. If things go wrong

If the build process fails, this may be due to a too old or too new Java version. See Where to get Java for more info on getting the latest version.

If anything else goes wrong, and you can’t get it right, ask for help on the firebird-devel list. Please give a good description of your problem, so we can help you better. If you aren’t on the firebird-devel list yet, visit https://groups.google.com/g/firebird-devel for information and subscription.

Appendix A: Building Chunked HTML For AsciiDoc

The primary output types we use are PDF and single-page HTML. However, for search engine optimization, it makes sense to have chunked output for some documents. Unfortunately, AsciiDoctor does not support chunked HTML output.

The workaround is to generate DocBook from the AsciiDoc sources, and then use DocBook stylesheets to produce chunked HTML.

Refer to the file devdoc/chunked_output.md in the repository for some — largely manual — steps to produce chunked output.

Appendix B: Document History

The exact file history is recorded in the firebird-documentation git repository; see https://github.com/FirebirdSQL/firebird-documentation

Revision History

0.1

2 Nov 2003

PV

First draft published under the title How to get and build the Firebird manual module.

0.2

31 Jan 2004

PV

Entered sources in CVS.

1.0

8 Mar 2004

PV

First official release on Firebird website.

1.1

26 Feb 2005

PV

The following changes have accumulated between March 2004 and Feb. 2005:

Added note on error messages during PDF build.

Added info on building subsets and non-English sets.

Added note on need to post-process PDF builds.

Changed title to Getting and building the Firebird manual module.

Numerous minor improvements.

Added document history and revision number.

Licensed this work under the Public Documentation License.

1.1.1

8 April 2005

PV

Added some titleabbrevs for presentational purposes. Contents as such unchanged.

1.2

9 Feb 2006

PV

Removed “Firebird” from title of 2nd section.

Added information on where to get the build libraries, since we don’t commit those to CVS anymore.

Created subsections for build parameters; added information on building other base sets and setting parameters in build.xml.

Changed docwritehowto link to ulink, as the articles will be in separate PDFs from now on.

1.2.1

15 May 2006

PV

Replaced cvs.sf.net (3x) and cvs.sourceforge.net (6x) with firebird.cvs.sourceforge.net to reflect new situation at SF. Also added “on one line” above two examples that are now line-wrapped in the PDF.

1.3

17 Jul 2006

PV

Changed all sectN elements to section.

Shortened ID of Introduction and assigned IDs to its child sections.

Spelling matters: RDMS → RDBMS, parallell → parallel, OS’es → OSes, CD’s → CDs, wil → will, envvar → envar, linewrapped → line-wrapped.

In section SSH checkout using command line CVS, 3rd listitem: converted <quote> around “username” to <replaceable>, changed “SF username” to “SF user name”, and also wrapped “username” in the command example in a <replaceable>.

In section SSH checkout using other clients, item cvsroot: wrapped “username” in a <replaceable>.

Gave the note in Building the HTML and PDF docs a title, and added a sentence to the second listitem.

Corrected rev. 1.1.1 date in document history: 2004 → 2005.

Added large section on improving the PDF.

1.4

3 Aug 2006

ND

Added warnings about firewalls and port 2401 plus how to cope when SourceForge changes your password.

1.4.1

23 Aug 2006

PV

Added warning against checking out over a pre-existing local copy.

1.5

5 May 2007

PV

Apart from the manual module, is there any other Firebird documentation? — Changed 2nd paragraph and list with links.

Do I really have to build the docs myself? — Changed 1st paragraph and removed all the links that followed.

Where to get the tools — Changed text throughout this section because we now download stuff to manual/lib and manual/tools.

How to set up the environment for the build — Change of wording in 2nd list item.

Building the HTML and PDF docs — In the note at the end: changed text and added link in the 2nd list item.

Building subsets with -Drootid — Changed the paragraph that starts with “How do you know the ID?”

Building a different base set with -Dbasename — Mentioned addition of papers set.

Advanced topic: Improving the PDF — Updated introductory paragraphs, including defects listing.

General repair scheme — Updated last list item in the Notes box.

Widowed headers — Heavily edited and id added; also moved part of content into new subsection When there is no DocBook ID.

Spaces in filenames, URLs etc. — Deleted.

Split table rows — Altered title, added id, altered Problem and Cause paragraphs.

Overly wide horizontal spaces — Added id.

Inserting zero-width spaces — Added id, slightly reworded the first two list items and removed the third.

Squeezed, truncated or otherwise messed-up page-sized content — Added.

XSL-FO references — Changed FOP version number in last paragraph.

License notice — © 2003-2006 → 2003-2007.

1.6

24 Oct 2009

PV

Checking out the manual module — Added warning against placing the local copy in a path with spaces or other “URL-unsafe” characters. Placed warnings in itemized list, gave warning element an explicit title, and changed the paragraph above.

Building the HTML and PDF docs — Added warning against path names that may change by URL-encoding, and provided a workaround. Gave ids to the five subsections.

Building subsets with -D[root]id, Building a different base set with -Dbase[name], Setting default values in build.xml and How the PDF is built — Replaced -Drootid with -Did and -Dbasename with -Dbase throughout these sections.

Building subsets with -Did — Changed first paragraph.

Building a different base set with -Dbase — Changed paragraph starting with “Meanwhile…​”.

If things go wrong — Inserted a paragraph on the problem with URL-unsafe characters in the path name.

When there is no DocBook ID — Gave this subsection an id.

Inserting zero-width spaces — Changed wording of second list item.

License notice — © 2003-2007 → 2003-2009.

1.6.1

26 Oct 2009

PV

Building the HTML and PDF docs — Fixed the IDs of this section and five of its subsections, which contained the word “buidling” instead of “building”:

  • docbuildhowto-buidling-output-docs

  • docbuildhowto-buidling-non-english

  • docbuildhowto-buidling-subsets

  • docbuildhowto-buidling-other-basesets

  • docbuildhowto-buidling-defaults

  • docbuildhowto-buidling-conclusion

If things go wrong — Fixed link to Building the HTML and PDF docs: buidling → building. In the same sentence, the words “at the end of” have been changed to “in”, because the link target is not at the end of the section (it’s just before the first subsection).

When there is no DocBook ID — Removed ID attribute from title element, because it was a) unnecessary, and b) a duplicate of the section ID and therefore illegal.

1.6.2

10 Feb 2013

PMA

Fixed some old links for Java JRE, replaced Java 2 reference with just Java, cvs home page is now fixed

1.7.0

25 Jan 2020

MR

Replaced CVS instructions with git instructions

2.0.0

29 February 2020

MR

Added instructions for the new Gradle-based build

2.0.1

19 May 2020

MR

Converted document to asciidoc

2.1.0

21 May 2020

MR

Added instructions for asciidoc tasks and some copy editing.

Fixed conversion from <sgmltag class="starttag"> to include the angle brackets.

2.1.1

23 May 2020

MR

Fixed rendering issue with bare link immediately followed by a -- generated em-dash

2.1.2

23 May 2020

MR

Updated link to Firebird Docwriting Guide

2.1.3

06 Jun 2023

MR

Replaced firebird-docs references with firebird-devel

2.1.4

09 Feb 2026

MR

  • Minimum Java version was raised to Java 17

  • Misc. copy-editing

2.2.0

30 May 2026

MR

  • Removed DocBook 4 build instructions

  • Various copy editing

  • Replaced chunked instructions with link to more up-to-date devdoc instructions

Appendix C: License notice

The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the “License”); you may only use this Documentation if you comply with the terms of this License. Copies of the License are available at https://www.firebirdsql.org/pdfmanual/pdl.pdf (PDF) and https://www.firebirdsql.org/manual/pdl.html (HTML).

The Original Documentation is titled Getting and building the Firebird manual module.

The Initial Writer of the Original Documentation is: Paul Vinkenoog.

Copyright © 2003-2026. All Rights Reserved. Initial Writer contact: paulvink at users dot sourceforge dot net.

Contributor: Norman Dunbar — see document history.

Portions created by Norman Dunbar are Copyright © 2006. All Rights Reserved. Contributor contact: norman at dunbar-it dot co dot uk.

Contributor: Mark Rotteveel — see document history.

Portions created by Mark Rotteveel are Copyright © 2020-2026. All Rights Reserved. Contributor contact: mark at lawinegevaar dot nl.