What is the difference between the -i and -u parameters to the dcc command-line compilers?

Question

What exactly is the -i option of the Delphi dcc command-line compilers (dcc32.exe, dcc64.exe, dcclinux64.exe and others)? As opposed to -u? Help just states this briefly (and Embarcadero documentation does not seem to expand upon the subject):

    -I<paths> = Include directories
    -U<paths> = Unit directories

For a while, I thought that -u is for including source code and -i for including precompiled .dcu files, but that does not seem to be the case. I also see cases where -i imports source code and -u imports .dcu files, and also that seems to work just fine. Another thought is that -u is meant to be the counterpart of the project's Search path in the Delphi IDE, and -i the counterpart of the Delphi IDE's global Library path, but that does not seem conclusive, either.

When should I use one or the other, -i or -u?

Answer 1

The Remarks section of this page http://docwiki.embarcadero.com/RADStudio/Sydney/en/Include_file_(Delphi) begins

The $I parameter directive instructs the compiler to include the named file in the compilation. In effect, the file is inserted in the compiled text right after the {$I filename} directive.

The default extension for filename is .pas. A filename specified with no file extension always gets the .pas extension. If the filename does not specify a directory path, then, in addition to searching for the file in the same directory as the current module, Delphi searches in the directories specified in the Search path input box on the Delphi Compiler page of the Project > Options dialog box (or in the directories specified in a -I option on the command line compiler). ..."

The important thing to understand is that this is not talking about searching for source files in general, but rather for single files named in a source file by an

{$inc }

or

{$include }

directive in a source file. For example

unit SomeUnit;

{$inc SomeIncludeFile}

interface

[...]

Files named inside an {$inc} or {$include} directive are known as "include files" - hence the title topic of the quoted page. Subject to the restriction noted in the final paragraph of the Remarks, the directive can appear pretty much anywhere in a source file and, during compilation, the compiler substitutes the contents of the named file for the directive (including the filename). The support for include files in Turbo Pascal pre-dates its support for units and was primarily to ensure that two or more source files could behave as if they contained identical text, for example shared code or definitions.

The -i setting tells the compiler one or more folders in which to look for files such as SomeIncludeFile which are named by include directives the compiler encounters while compiling the source files in a project.

The -u setting tells the compiler where to look for unit files (e.g. .Pas and .Dcu ones) during a compilation.