Delphi XE2: What is the purpose of IMPLICITBUILDING directive found in package

When I attempt to create a new package in Delphi XE2, there is a new construct in package dpk source file: IMPLICITBUILDING

What is that for?

package Package1;

{$R *.res}
{$IFDEF IMPLICITBUILDING This IFDEF should not be used by users}
{$ALIGN 8}
{$ASSERTIONS ON}
{$BOOLEVAL OFF}
{$DEBUGINFO ON}
{$EXTENDEDSYNTAX ON}
{$IMPORTEDDATA ON}
{$IOCHECKS ON}
{$LOCALSYMBOLS ON}
{$LONGSTRINGS ON}
{$OPENSTRINGS ON}
{$OPTIMIZATION OFF}
{$OVERFLOWCHECKS OFF}
{$RANGECHECKS OFF}
{$REFERENCEINFO ON}
{$SAFEDIVIDE OFF}
{$STACKFRAMES ON}
{$TYPEDADDRESS OFF}
{$VARSTRINGCHECKS ON}
{$WRITEABLECONST OFF}
{$MINENUMSIZE 1}
{$IMAGEBASE $400000}
{$DEFINE DEBUG}
{$ENDIF IMPLICITBUILDING}
{$IMPLICITBUILD ON}

requires
  rtl;

end.

Here is an excerpt from my "Delphi in all its glory [Part 3]" book.

(Sorry, there ware supposed to be images in here, but StackOverflow won't show them after copy/paste).

Implicit building
When working with Delphi packages, you might encounter a section at the beginning of .dpk files (Delphi package files) that looks something like this:

Package LightSaber;

{$IFDEF IMPLICITBUILDING This IFDEF should not be used by users}
  {$ALIGN 8}
  {$ASSERTIONS ON}
  {$DEBUGINFO OFF}
  {$IOCHECKS ON}
  {$LOCALSYMBOLS ON}
  {$OPTIMIZATION OFF}
  {$OVERFLOWCHECKS ON}
  {$RANGECHECKS ON}
  {$REFERENCEINFO ON}
  {$DEFINE DEBUG}
  {$ENDIF IMPLICITBUILDING}
{$LIBSUFFIX AUTO}
{$RUNONLY}
{$IMPLICITBUILD ON}

This block of code contains compiler directives, which influence how the compiler behaves during the build process. However, because of {$IFDEF IMPLICITBUILDING}, they apply only if implicit building is on ($IMPLICITBUILD ON)

What is implicit/explicit building?

Implicit building
Implicit building refers to the process where a package (or library) is automatically recompiled if needed by another package or project, if the package hasn't been explicitly built beforehand. For example, if package B depends on package A, and package A has not been compiled yet, the compiler will first compile package A, then package B.

Explicit building
When you set your project to explicit building, the compiler will not re-compile the package A automatically. Instead, it will generate an error forcing you to explicitly recompile package A before proceeding with the compilation of package B. In other words, in explicit building you are responsible to compile the packages through the IDE or through a project group.

The role of {$IFDEF IMPLICITBUILDING}

The {$IFDEF IMPLICITBUILDING} switch ensures that the directives (assertions, debug info, IO checks, optimizations, etc, etc) inside the DPK file are only applied during implicit building. When the package is being compiled explicitly, these directives are simply ignored, preventing conflicts with the compiler's build options. Potential issues with implicit building While implicit building might seem convenient, it can cause problems in larger projects, especially when targeting multiple platforms or using different configurations (debug vs. release). Here’s why:

1. Inconsistent configuration: Since the .dpk file contains a single set of settings, they may not match the current project’s build configuration (e.g., the .dpk may specify DEBUG, but you're compiling in release mode).
2. Cross-platform builds: If you're building for multiple platforms (e.g., Win32, Win64, macOS), fixed settings in the .dpk may not be appropriate for all platforms, leading to build errors or misconfigurations.
3. Command-line compilation: When compiling packages from the command line, the IDE-generated options may not be applied correctly.

Implicit or Explicit?

Given the issues outlined above, it's often better to disable implicit building and explicitly compile all necessary packages. This can be done by setting {$IMPLICITBUILD OFF}. In this case, if a package hasn't been compiled yet, the compiler will throw an error, prompting you to build the package manually. This ensures that you have full control over the build process. To simplify the build process, you can create project groups to manage multiple packages and ensure that they are built in the correct order and with the correct settings.

You can set the implicit/implicit mode in Project’s Options. Be aware that instead of “Implicit” they use “Rebuild as needed”.

Recap
• Implicit building is convenient as it can simplify the build process for small projects targeting a single platform. However, in complex projects, it’s generally better to disable implicit building and take control of the build process through explicit compilation.
• In explicit mode, if a package needs to be rebuilt, the compiler will show an error and you will have to manually compile that package in the correct mode (debug/release/win32/win64/etc).
• Using project groups can come quite handy if you compile in explicit mode.
• You can still have package in implicit mode, and compile it from the Project Manager manually, for the config you need it (debug/release/win32/win64/etc).

---

Please also see this discussion: Why does Delphi change Indy's dpk source file when I change project options and this.