Compiling Code

• The Command Line
• A Simple Example
• Compilation Process
• Compiler Options
• Choosing a memory model
• Compiling for debugging
• Internationalization Options
• Compiling for floating-point emulation and math coprocessors

#include <stdio.h>

void main()
{
    printf("hello world!\n");
}

dmc hello

hello

hello world!

The compiler executables can compile either C or C++ files. The preprocessor is integrated in; but for specialized applications a separate standalone preprocessor is also included.

As it runs, the compiler reads the source files, executes all preprocessor functions, checks for any syntax errors, optimizes the program, generates machine code, and outputs an object (.obj) file suitable for input to the linker.

Startup code

There are several files that contain startup functions (all with different names) in several subdirectories of the Digital Mars \dm\src directory.

Compiler Options

Specifying compiler output

-cod Generate assembly language output file

-e Show preprocessor output

-EC Leave comments in preprocessed output

-EL Do not emit #line directives

-l[listfile] Generate source listing file

-ofilename Specify output .obj or .exe filename

-v[0|1|2] verbose compile

Support for C language features

-A Enforce strict compliance with ANSI C

-J Treat chars as unsigned

-Jm Relax type-checking

-Ju char and unsigned char are the same type (unsigned char)

-p Turn off function auto-prototyping

-r Require strict function prototyping

-u Suppress non-ANSI predefined macros

Support for C++ language features

-A Enforce strict compliance with ANSI C++

-Ar Enable run time type identification

-Ae Enable exception handling

-cpp Compile all source files as C++

-J Treat chars as unsigned

-u Suppress non-ANSI predefined macros

Suppressing warnings and errors

-w Suppress all warning messages

-w[number] Suppressing warning message number

-w- Show all compiler warnings

-wx Treat warnings as errors

-x Turn off compilation error limit

Dynamic profiling

-gt and -Nc Turn on dynamic profiling.

Memory model choices trade off between meeting minimum system requirements, maximizing code efficiency, and accessing as much available memory as possible.

For more information, see Chapter 7, "Choosing a Memory Model." To specify the memory model, use the dmc options described below or use the Memory Models subpage on the Build page of the IDDE's Project Settings dialog box.

For more information on memory allocation, see Chapter 5, "Using Assembly Language Functions."

-m[tsmclvfnrpxz][do][w][u] Select memory model

Note: For Win32, it is imperative that SS==DS==ES at all times. Otherwise the Win32 API functions will crash. (CS need not be equal to SS, FS is reserved for thread-related information, and GS is available for general use.) Thus, SS==DS==ES for the Win32 (-mn) memory model.

Here are some example combinations of memory model specifiers:

-ms		Small model with SS == DS 
-msw		Small model SS != DS 
-mc		Compact model 
-mt		.com file 
-mluw		Large model, SS != DS, Reload DS 

The program stack

In all memory models, the stack grows downward toward statically allocated data. If the stack grows larger than its allocated size, statically allocated data are destroyed, and the program performs unpredictably. To check if the stack grows past the allocated limit, use the special function called _chkstack.

Call _chkstack from functions that potentially use large amounts of stack space, such as recursive functions. If the stack exceeds the allocated size, _chkstack aborts the program with the message:

Stack overflow 

Controlling stack size for DOS programs

• Use the =nnnn command line option (see below) when running the program.
• Include the declaration

  unsigned __cdecl _stack = nnnn;
  

  in the program source code, where nnnn is the size in bytes that you want the stack to be. For C++ code, use:

  extern "C" unsigned __cdecl _stack = nnnn; 
  

  Note that the declaration must appear just as described above to work correctly.
• Modify the c.asm startup module.

For a DOS program, do not use the linker /STACK parameter to set the stack size; use one of the methods described above. The default stack size is 8192 bytes for 16-bit compilations and 16KB for 32-bit compilations.

-s Check for stack overflow

Aligning data objects

You can control alignment only within structures; the compiler still aligns all other data objects on word or dword boundaries.

Struct member alignment can also be specified with the #pragma pack preprocessor directive. Refer to Chapter 3, "Digital Mars C++ Language Implementation" for more information.

The C++ compiler does not generate structs with a size of 0 bytes if there are no nonstatic data members; the minimum size of a struct is 1 byte. This prevents new() from returning 0 when it tries to allocate an instance of a struct.

Warning: Each file referencing a structure must be compiled with the same type of alignment. If two files compiled with different alignment reference the same structure, any erroneous results could be hard to debug.

-a Specify structure member alignment

There are two basic types of debugger that can be used with Digital Mars C and C++ programs: fully symbolic debuggers (those that work with symbolic information, like the Digital Mars debuggers or Microsoft Corporation's CodeView), and partially symbolic debuggers (those that require only source code line numbers and map file information, such as Microsoft's Symdeb).

Compatibility with third-party C debuggers

The Digital Mars C and C++ debuggers can display, modify, and track all the local variables within a function.

Compatibility with third-party C++ debuggers

• C++ function names are displayed by the debugger in their mangled form, as used internally by the compiler.
• Expanding a derived class shows only those variables added in the derived class. Base-class variables cannot be seen.
• Pointers to a base class always are shown as such, even if they really point to a derived class.
• Inline functions can cause some debuggers severe problems and must be avoided.
• C debuggers have no facilities for examining class definitions or hierarchies.

Overview of compiler debugging options

• Full symbolic debugging and line number information (-g option) for all variables used in a module. Programs can be debugged at the source level with full debugging information.
• Symbolic information only (-gs option). This provides all the symbolic information but does not generate any line number information. This level conserves space and allows the debugger to work on larger programs but prevents debugging at the source level; programs must be debugged at the object code level.
• Symbolic information for global structs and typedefs, whether they are referenced or not, as well as for all variables referenced (-gh option).
• Symbolic information for each class that the generated code references, as well as for all variables referenced. (-gf option).
• Line numbers only (-gl option). This option is mainly for use with partially symbolic debuggers. It emits no symbolic information, except what is normally placed in the linker map file. This level provides full line number information. This allows debugging at the source code level, but only global symbols are available; local and static symbols cannot be observed.

Debugging options

-C Prevent inline expansion of C++ functions

-g Generate debug info for types of referenced variables

-g4 Generate Codeview 4 format debug info. This is the default.

-gf Generate debug info for full class hierarchy for any referenced classes.

-gg Make static functions global

-gh Generate debug info for all global structs and typedefs

-gl Generate line number info only

-gp Generate pointer validation code

-gs Generate symbol info only (do not generate line number info)

-gt Generate prolog/epilog for use with the dynamic profiler. -S Always generate stack frame

Linking for debugging

These are the options for Digital Mars OPTLINK or Microsoft LINK for all levels of debugging information:

• /m (create map file)
• /co (link for CodeView)
• To use Microsoft LINK, specify the -Llinker compiler option. linker is which linker to run. Only Microsoft LINK 5.1 or later versions correctly handle the symbolic information.

See the User's Guide and Reference for more information on using the Digital Mars debuggers.

Notes on debugging with CodeView

• CodeView cannot handle inline functions.
• Make each statement in the source code occupy a separate line. Also, CodeView does not break down complex macros, so if you suspect a macro of containing a bug, write the macro as a regular source statement.
• Compile source modules with the -g option and link with the /co (CodeView) and /noi (do-not-ignore case) options.
• An apparent limitation causes CodeView for Windows to halt unexpectedly if you attempt to debug executables that contain large tables, such as applications built with MFC and compiled with Digital Mars C++. One workaround is to find the table that exceeds the maximum size, rebuild the objects that contribute to it without debugging information, and then re-link. Or, relink the with OPTLINK using the /NODEBUG and /DEBUG options (no need to recompile).

Debugging aids in the run-time library

• If a NULL pointer is passed to printf where a pointer to a string is expected, printf uses the string "null" instead. For example:

  printf("String '%s'\n", NULL); 
  

  prints:

  String '(null)' 
  

• If a NULL near pointer is de-referenced, the string that is at location 0 in the data segment is "ERROR: NULL pointer." For example:

  char buf[100];
  strcpy(buf, NULL); 
  printf("String '%s'\n", buf); 
  

  prints (for code compiled with the Tiny, Small, and Medium models):

  String 'ERROR: NULL pointer' 
  

Specifying linker and assembler options

-L Using non-Digital Mars linker.

-Llinker Use linker linker instead of OPTLINK.

-L/switch Pass /switch to linker.

-Masm Use assembler asm instead of MASM.

-M/switch Pass /switch to assembler.

Controlling segmentation

• Use the -NTcsname compiler option, which sets the code segment for a file to be csname.
• Use the -NS compiler option, which creates a new code segment each time the compiler encounters a global far function. The name of the segment is the name of the function, with _TEXT appended.
• For Compact and Large model compilations, use the -GT compiler option, which places arrays larger than a specified number of bytes in far data segments instead of DGROUP.
• Use the #pragma:

  #pragma SC cseg csname 
  

  which places what follows in the segment csname. The -NS option overrides the #pragma for global far functions.

Preventing data segment overflow

• Compile with the -R option, which causes switch statement tables to be placed in the code segment rather than in DGROUP.
• Declare literal strings you want to place in the code segment with the type modifier __cs.
• Compile with the -Ns option, which places strings that are part of expressions into the code segment rather than in DGROUP.
• Declare statically allocated data as far; for example: int __far array[100];

Data declared as far should be data that is relatively large and is accessed relatively infrequently, as more overhead is required to access those data.

If another module should reference far static data, declare it as far, as in:

extern int __far array[]; 

Virtual function tables (vtbls)

To further minimize use of code space in Compact and Large model programs, place vtbls in far data segments with -NV.

Segmentation options

-NS Create new code segments for far functions

-Ns Put strings in expressions into code segment

-NTname Set code segment name to name.

-NV Put virtual function tables in far data segments.

-R Put switch tables in code segment

-GTnnnn Put large arrays in far data segments.

Code generation options

-0, -2, -3, -4, -5, -6 Specify CPU instruction set

-c Compile only, do not link executable.

-C Disable inline function expansion.

-D[macro[=text]] Define macro

-Nc Perform function level linking

-NF ignore extended keywords

-NL Do not embed default library record

-o Optimize code for speed

-o+space Optimize code for space

-P Default to pascal linkage

Compiling for Windows

Templates

-XIspec Create instance of template

-XD instantiate template for any functions declared but not defined

-XN no template function instantiation

-j[0|1|2] Recognize multibyte Asian language characters in the source