Liren Large Software Subsidy 7

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 7 / 07.iso / c / c500 / 1.ddi / WCCOPTS.HPK / WCCOPTS.HLP

(.txt)

Wrap

OS/2 Help File | 1992-05-28 | 24.5 KB | 710 lines

ΓòÉΓòÉΓòÉ 1. General Information on Compiler Options ΓòÉΓòÉΓòÉ The dialog entitled WATCOM C/386 Compiler Options allows you to specify the compiler options that will be used to compile your application. These options are separated into categories. To view or modify the options in a particular category, select the push button for that category. Four push buttons are located at the bottom of each dialog. Selecting the push button entitled OK terminates the dialog and returns you to the main dialog, saving all changes made to that dialog. If you select OK in the main dialog, your session will also be terminated and you will be returned to the project dialog. If Save to project has been selected, your changes will be updated in the project profile so that your changes will be reflected in subsequent sessions with this project. Selecting the push button entitled Default will set all options appearing in the dialog to their default values. If you select Default in the main dialog, all options in all dialogs will be set to their default values. Selecting the push button entitled Cancel terminates the dialog; any changes made to the dialog will be discarded. If you select Cancel in the main dialog, your session will be terminated and all changes will be discarded. Selecting the push button entitled Help provides information on all the options appearing in the dialog. ΓòÉΓòÉΓòÉ 2. Optimizations ΓòÉΓòÉΓòÉ The C/386 optimizing compiler is capable of performing many types of optimizations. The dialog entitled Optimizations allows you to specify the optimizations you wish the compiler to perform. Disable Optimizations Selecting Disable optimizations causes the compiler to suppress optimizations. The resulting code may be larger and execute slower but will be much easier to debug. Loop Optimizations Selecting Loop optimizations causes the compiler to perform loop optimizations. Loop optimizations include the following. Loop-invariant code motion If an expression exists inside a loop and its operands are not modified by subsequent iterations of the loop, the compiler will compute the expression outside of the loop. Loop-induction expression detection An induction variable is a linear function of a variable which is incremented by a constant value within a loop. An example is A[I] where A is an array appearing in a for-loop with loop-variable I. Reduction in strength Induction expressions like A[I] may be replaced by a simple pointer variable which is incremented by the appropriate amount on each loop iteration, eliminating costly multiplication operations within the loop. Loop-induction variable elimination Reduction in strength may eliminate all references to a variable like I, except possibly in the loop termination test. In this case, I may be eliminated altogether if the loop termination test is modified to use an introduced pointer variable. Math Optimizations When the "fpi" or "fpi87" compiler option is selected, the compiler generates 80x87 floating-point instructions to perform the basic arithmetic operations of addition, subtraction, multiplication and division. In addition, the math coprocessor contains specialized floating-point instructions that can be used to implement various mathematical intrinsic functions. For example, a single instruction can be used to implement the SIN, COS, SQRT and TAN intrinsic functions. Also, a relatively small number of instructions can be used to implement the LOG10 and LOG intrinsic functions. By default, a call to a run-time routine is generated when a call to any of the above intrinsic functions is made. Selecting Math Optimizations causes the compiler to generate specialized floating-point instructions instead of calls to run-time routines. CAUTION: Note that argument validation is not performed when math optimizations are performed. You should select math optimizations only if the arguments to these functions are valid ones. Call/Return Optimizations Selecting Call/Return optimizations disables the optimization where a "call" intstruction followed by a "ret" (return) instruction is changed into a "jmp" (jump) instruction. In-line Intrinsic Functions Selecting In-line intrinsic functions causes the compiler to generate certain library functions in-line. You must include the appropriate header file containing the prototype for the desired function so that it will be generated in-line. The functions that can be generated in-line are: abs, _disable, div, _enable, fabs, labs, ldiv, _lrotl, _lrotr, inp, inpw, memchr, memcmp, memcpy, memset, movedata, outp, outpw, _rotl, _rotr, strcat, strchr, strcpy, and strlen. The macro "__INLINE_FUNCTIONS__" is also predefined by the compiler. Relax Alias Checking Selecting Relax alias checking causes the code optimizer to assume that global variables are not indirectly referenced through pointers. This assumption may reduce the size of the code that is generated. The following example helps to illustrate this point. extern int i; void rtn( int *pi ) { int k; for( k = 0; k < 10; ++k ) { (*pi)++; i++; } } In the above example, if "i" and "*pi" referenced the same integer object then "i" would be incremented by 2 each time through the "for" loop and we would call the pointer reference "*pi" an alias for the variable "i". In this situation, the compiler could not bind the variable "i" to a register without making sure that the "in-memory" copy of "i" was kept up-to-date. In most cases, the above situation does not arise. Rarely would we reference the same variable directly by name and indirectly through a pointer in the same routine. This option instructs the code generator that such cases do not arise in the module to be compiled. The code generator will be able to produce more efficient code when it does not have to worry about the alias "problem". Instruction Scheduling Selecting Instruction scheduling causes the compiler to perform an optimization phase called instruction scheduling. When instruction scheduling is performed, the compiler will generate instructions in an an order that attempts to maximize the use of the instruction pipeline. Expand Functions In-line Selecting Instruction scheduling causes the compiler to expand certain user-defined functions in-line. The criteria for which functions are selected for in-line expansion is based on the "size" of the function in terms of the number of operations generated for the function. The number of operations corresponds closely to the number of operators. Functions which require more than a certain number of operations are not expanded in-line. This value can be specified by selecting # of operations. The default number is 20. This optimization is useful when locally-referenced functions are small in size. Generate Stack Frames As Needed Selecting Generate stack frames as needed forces the generation of traceable stack frames for functions that contain calls or require stack frame setup. For near functions, the following function prologue sequence is generated. push EBP mov EBP,ESP For far functions, the following function prologue sequence is generated. inc EBP push EBP mov EBP,ESP The EBP value on the stack will be even or odd depending on the code model. Always Generate Stack Frames Selecting Always Generate Stack Frames forces the generation of traceable stack frames even if they are not required. Space Versus Time Optimizations Selecting Space optimizations causes the compiler to generate smaller code at the expense of execution speed. Selecting Time optimizations causes the compiler to generate faster executing code at the expense of code size. The generated code may be larger but will execute faster. Selecting Average space and time causes the compiler to select a balance between space and time. ΓòÉΓòÉΓòÉ 3. Debugging Information ΓòÉΓòÉΓòÉ Debugging information is generated by the compiler when creating an object file. The linker, when instructed to do so, will collect debugging information from object files and place it in the executable file. The debugging information in the executable file can then be used by the debugger. The dialog entitled Debugging Information allows you to specify the amount of debugging information you wish the compiler to generate. Selecting No debugging information causes the compiler to generate no debugging information. Selecting Line number information causes the compiler to generate only line numbering information. This allows source-level debugging of your application. If optimizations are not disabled, the mapping of a line of source to its equivalent assembly language intructions may not be accurate. Selecting Line # and automatic symbol information causes the compiler to generate line number and automatic symbol debugging information. In addition to source-level debugging, this level of debugging information allows the referencing automatic variables by name. Selecting Full debugging information causes the compiler to generate line numbering information as well as local symbol and typing information. Local symbol and typing information allows you to examine the contents of the variables in your function by referencing their name. Note that optimizations will be disabled automatically when requesting full debugging information. Selecting Emit routine names in code causes the compiler to emit the function name into the object code as a string of characters just before the function prologue sequence is generated. The string is terminated by a byte count of the number of characters in the string. This option is intended for developers of embedded systems (ROM-based applications). ΓòÉΓòÉΓòÉ 4. File Management Options ΓòÉΓòÉΓòÉ The dialog entitled File Management Options allows you to control the generation and contents of output files produced by the compiler. Selecting Force Include File: allows you to specify a file that is included as if a #include "<file_name>" directive were placed at the start of the source file. Simply type the name of the include file in the field immediately below (a cursor should be present). Selecting Include Directories: allows you to specify a list of directories in which the compiler will search for files included using the "include" compiler directive. To add a directory, select Include Directories: . A cursor will appear in the entry field immediately below. Type the name of the directory and press the "Enter" key. The directory will be displayed in the list box immediately below. To delete a directory from the list, select it from the list of directories and then select the Delete push button. The name of the object file is constructed from the source file name and has file extension "OBJ". Selecting Name object file: allows you to specify an alternate name for the object file or the destination of the object file. Examples: c:\c\obj\ specifies that the object file is to be placed in the directory "c:\c\obj". Note that a trailing "\" must be specified with directory names, otherwise the directory name will be assumed to be a file name. c:\c\obj\*.dbo specifies the the object file is to be placed in the directory "c:\c\obj" with file extension "DBO" instead of "OBJ". The file name will be the same as the file name of the source file. Selecting Generate function prototypes will cause the compiler to output function declarations to a file with the same filename as the C source file but with extension ".def". This file, called a definition file, may be used as an include file when compiling other modules in order to take advantage of the compiler's function and argument type checking. Selecting Generate function declarations will also cause a definition file to be created. The output is similar to that created when Generate function prototypes is selected except that function declarations will be output to the definitino file using base types (i.e., typedefs are reduced to their base type). If Do not generate definition file is selected no definition file will be generated. ΓòÉΓòÉΓòÉ 5. Code Generation Strategy ΓòÉΓòÉΓòÉ The dialog entitled Code Generation Strategy allows you to specify the memory model, floating-point model, calling convention and the target processor to be used for code generation. Memory Models Memory models are distinguished by two properties: the code model used to implement function calls and the data model used to reference data. There are two code models; small and big. A small code model is one in which all calls to a function are made with near calls. In a near call, the destination address is 32 bits and is relative to the segment value in segment register CS. A big code model is one in which all calls to a function are made with far calls. In a far call, the destination address consists of a 16-bit segment and a 32-bit offset relative to the segment value. There are also two data models; small and big. A small data model is one in which all references to data are made with near pointers. Near pointers are 32 bits; all data references are made relative to the segment value in segment register DS. A big data model is one in which all references to data are made with far pointers. Far pointers consist of a 16-bit segment and a 32-bit offset relative to the segment value. The following memory models are supported by the compiler. Flat memory model Small code and small data models are used. The applications code and data reside in the same linear address space. That is, an offset in the data segment refers to the same memory location as that offset in the code segment. Small memory model Small code and small data models are used. The flat memory model requires that the applications code and data must reside in the same linear address space; the small memory model does not. Medium memory model Big code and small data models are used. Compact memory model Small code and big data models are used. Large memory model Big code and big data models are used. CAUTION: If you are developing an OS/2 2.x application, you should only specify the flat memory model. Other memory models are available for developing applications for other target environments. Floating-point Models There are four floating-point models. In-line 80287 instructions The compiler will generate floating-point instructions in-line. Only 80287 instructions will be generated. This is required if you will be running your application on a 386 machine that is equipped with an 80287 math coprocessor. In-line 80387 instructions The compiler will generate floating-point instructions in-line. The generated floating-point instructions will only run on a machine that is equipped with an 80387 math coprocessor. In-line 80x87 with emulator The compiler will generate floating-point instructions in-line and will cause an emulator to be linked with your application. Since OS/2 2.x has a built-in emulator, this is equivalent to selecting In-line 80387 instructions This option is to be used when the operating system under which your application is to run does not support emulation of a math coprocessor. Floating-point calls The compiler will generate calls to run-time routines to perform floating-point operations. The floating-point run-time routines check for the existence of a math coprocessor. If one is present it will be used; otherwise the operations will be implemented using 80386 instructions. Calling Conventions There are two calling conventions that can be selected through compiler options. Register-based The compiler will pass arguments in registers EAX, EDX, EBX and ECX. All registers, including floating-point registers, will be saved and restored accross calls. Stack-based The compiler will pass arguments using the 80386 stack. Only registers EBX, ESI and EDI will be saved and restored accross calls; all other registers, including floating-point registers, will not. Target Processor Selecting Assume 80486 processor instructs the compiler that you wish to target your application for an 80486 processor. In this case, specialized code sequences can be generated that will result in improved execution speed on computers equipped with an 80486. Note that the code will still execute on a computer equipped with an 80386 processor but may execute slower than the code generated if this option was not selected. Select Assume 80386 processor if you wish to optimize your application strictly for an 80386 processor. ΓòÉΓòÉΓòÉ 6. Code Generation Options ΓòÉΓòÉΓòÉ The dialog entitled Code Generation Options allows you to specify options that affect the generated code. Selecting Name Code Group: allows you to specify a group name for code segments. To specify the code group, select Name Code Group: . A cursor will appear in the entry field immediately to the right at which point you may type the name of the code group. By default, code segments are not placed in a group. Selecting Name Code Class: allows you to specify an alternate name for the code class. To specify the code class, select Name Code Class: . A cursor will appear in the entry field immediately to the right at which point you may type the name of the code class. The default code class name is "CODE". Selecting Name Data Segment: allows you to specify a prefix for all segments that belong to the default data segment. The prefix is also used to name the default data segment. To specify the prefix to be used, select Name Data Segment: . A cursor will appear in the entry field immediately to the right at which point you may type the prefix. Selecting Name Text Segment: allows you to specify an alternate name for the text segment. The text segment is the segment in which generated code is placed. To specify the name of the text segment, select Name Text Segment: . A cursor will appear in the entry field immediately to the right at which point you may type the name of the text segment. By default, the text segment name is "_TEXT" for small code models and "<module_name>_TEXT" for large code models. Selecting Name of Module: allows you to specify the module name that is placed into the object file. To specify the module name, select Name of Module: . A cursor will appear in the entry field immediately to the right at which point you may type the module name. By default, the object file name and the module name that is placed within it are constructed from the source file name. Selecting Generate default libraries instructs the compiler to generate default libraries in the object file. The default libraries generated are selected based on the memory model, floating-point model, and calling convention. Selecting Easy OMF-386 object files instructs the compiler to generate object files that conform to the Phar Lap Easy OMF-386 object module specification. This option should only be specified if you are using Phar Lap development tools to create 386 DOS protected mode applications. Selecting Save/Restore segment registers instructs the compiler to generate function prologue and epilogue sequences that save and restore any segment registers that are modified by the function. CAUTION: If the value of the segment register being restored matches the value of a segment that was freed within the function, a general protection fault will occur. Selecting Segment register DS is fixed instructs the compiler the segment register DS cannot be used by the generated code. CAUTION: Under OS/2, segment register DS must not be modified as it is used to access data in the application's linear address space. Selecting Segment register FS is fixed tells the compiler that segment register FS cannot be used by the generated code. CAUTION: Under OS/2, segment register FS contains the segment of the thread information block of the current thread and must not be modified. Selecting Segment register SS not data segment tells the compiler that segment register SS does not contain the segment address of the default data segment. CAUTION: Under OS/2, segment register SS must not be modified as it is used to access the stack in the application's linear address space. Selecting Place functions in separate segment instructs the compiler to place each function in its own code segment. This option is used in paging environments where special segment ordering may be employed. The "alloc_text" pragma is often used in conjunction with this option to place functions into specific segments. The disadvantages to this option are: 1. Static functions are "far called" in big code models. The "near call" optimization is lost. 2. The "common epilogue" optimization is lost. Selecting Constants in code segment instructs the compiler to place constant data in the code segment. This includes character literals and numeric constants. ΓòÉΓòÉΓòÉ 7. Diagnostics ΓòÉΓòÉΓòÉ The dialog entitled Diagnostics allows you to specify what level of diagnostic information is required at compile-time and run-time. Warning messages have a severity number associated with them. Only warning messages whose severity is less than or equal a given severity level will be issued. Severity 1 warning messages are the most severe while severity 3 warning messages are the least severe. Selecting Warning level 0 suppresses all warning messages. Selecting Warning level 1 causes only severity 1 warning messages to be issued. This is the default. Selecting Warning level 2 causes severity 1 and 2 warning messages to be issued. Selecting Warning level 3 causes severity 1, 2 and 3 warning messages to be issued. Selecting Treat warnings as errors instructs the compiler to treat all warnings as errors, thereby preventing the compiler from creating an object file if there are warnings found within a module. By default, the compiler will continue to create an object file when there are warnings produced. Selecting Error Count: allows you to specify the number of errors the compiler will diagnose before stopping the compilation. To specify the maximum number of errors, select Error Count: . A cursor will appear in the entry field immediately to the right at which point you may type the maximum number of errors. By default, the compiler will stop compilation after 20 errors. Selecting Enable extensions instructs the compiler to allow extensions to the ANSI C specification. Selecting Stack checking instructs the compiler to generate a run-time call at the beginning of each function that checks for stack overflows. The OS/2 operating system allocates the stack as a sparse object in multiples of 4K. When you specify a stack size, it is rounded up to the nearest multiple of 4K. The 4K pages that comprise the stack are not all committed. Initially, only the page with the largest address is committed and the page below it is called a guard page. When the guard page is accessed, a guard-page exception is generated and handled by attempting to get another guard page below the one that caused the exception. If this is successful, the original guard page becomes committed and is now part of the regular stack. This process continues until a new guard page cannot be allocated. In this way the stack grows automatically. If a function's prologue requires more than 4K of automatic storage, it is possible to access a part of the stack that is below the guard page. If this happens, a protection-violation exception is generated and the application is terminated. Selecting Automatic stack growing causes the compiler to generate code that ensures that any access to automatic storage is not below the guard page. ΓòÉΓòÉΓòÉ 8. Source Processing Options ΓòÉΓòÉΓòÉ The dialog entitled Source Processing allows you to specify how the compiler will process source code. Selecting Run preprocessor only instructs the compiler to generate "#line" directives when the preprocessor is run. The "#line" directives allow the compiler to issue error messages in terms of the original source file line numbers. Selecting Preserve comments instructs the compiler to preserve comments in the original source file. Selecting Insert #line directives instructs the compiler to only run the preprocessor. No code is generated and no object file is produced. The output of the preprocessor is written to the standard output file, although it can also be redirected to a file using the "fo" option. A number of compiler directives are available that allow conditional compilation of source code. To define a macro symbol, select Macro: . A cursor will appear in the entry field immediately to the right. Type the name of the macro symbol and press the "Enter" key. If you wish to specify a value, place an equal sign after the macro name followed by the text that the macro is to be defined as. The macro information will be displayed in the box immediately below and will be preceded with a dot. The dot indicates that the macro is defined. To undefine a macro symbol, select it from the list of macro symbols and then select the Undefine push button. The dot preceding the macro symbol will disappear. Note that the macro symbol has not been removed from the list. To delete a macro from the list, select it from the list of macro symbols and then select the Delete push button. If you wish to redefine a macro that has been undefined, select it from the list of macro symbols and then select the Define push button. The dot preceding the macro symbol will reappear. Selecting Syntax check only instructs the compiler to scan the source code and make sure that it is syntactically correct; no object code will be generated. Selecting Force enums to be type int instructs the compiler to allocate an 'int' for all enumerated types. By default, the compiler will allocate the smallest storage unit required to hold all possible values given for an enumerated list. Selecting Change char default to signed instructs the compiler to change the default "char" type from an unsigned to a signed quantity. Selecting Structure packing alignment allows you to specify the alignment of members in a structure. The default value for the structure alignment is 1. The alignment of structure members is described in the following table. If the size of the member is 1, 2, 4 or 8, the alignment is given in the table. If the member of the structure is an array or structure, the alignment is described by the row "x". Alignment 1 2 4 8 sizeof(member) \------------------------------- 1 | 0 0 0 0 2 | 0 2 2 2 4 | 0 2 4 4 8 | 0 2 4 8 x | aligned to largest member An alignment of 0 means no alignment, 2 means word boundary, 4 means doubleword boundary, etc. If the largest member of structure "x" is 1 byte then "x" is not aligned. If the largest member of structure "x" is 2 bytes then "x" is aligned according to row 2. If the largest member of structure "x" is 4 bytes then "x" is aligned according to row 4. If the largest member of structure "x" is 8 bytes then "x" is aligned according to row 8. To understand why structure member alignment may be important, consider the following example. typedef struct memo_el { char date[9]; struct memo_el *prev,*next; ref_number int; } memo; In the above example, the default alignment value of 1 will cause the pointer and integer items to be aligned on odd addresses since the array "date" is 9 bytes in length. On computer systems that have a 16-bit (or 32-bit) bus, improved performance can be obtained when these items are aligned on an even boundary. ΓòÉΓòÉΓòÉ 9. Miscellaneous Compiler Options ΓòÉΓòÉΓòÉ The dialog entitled Miscellaneous Compiler Options lists a number of miscellaneous compiler options. Selecting Messages to terminal instructs the compiler to display all messages to the terminal. Selecting Ignore WCL386 environment variable causes the WCL386 environment variable to be ignored. The WCL386 environment can also be used to specify options. Selecting Data threshold: allows you to set the minimum size for data objects to be included in the default data segment. This option is only useful for memory models that have big data models where arrays larger than the data threshold are allocated outside the default data segment. Double-Byte Character Support The compiler can recognize double-byte characters in strings. When the compiler scans a text string enclosed in quotes ("), it will recognize the first byte of a double-byte character and suppress lexical analysis of the second byte. This will prevent the compiler from misinterpreting the second byte as a "\" or quote (") character. Selecting Kanji causes the compiler to process strings for Japanese double-byte characters (range 0x81 - 0x9F and 0xE0 - 0xFC). The characters in the range A0 - DF are single-byte Hiragana. Selecting Chinese/Taiwanese causes the compiler to process strings for Traditional Chinese and Taiwanese double-byte characters (range 0x81 - 0xFC). Selecting Chinese/Taiwanese causes the compiler to process strings for Korean Hangeul double-byte characters (range 0x81 - 0xFD). Selecting No double-byte character support suppresses the double-byte character processing by the compiler. ΓòÉΓòÉΓòÉ 10. Linker Options ΓòÉΓòÉΓòÉ The dialog entitled Linker Options allows you to specify options that affect the linking of your application. Selecting Compile only, no linking will cause your application to be compiled only; the linker will not be invoked. Selecting Stack size: allows you to set the size of the stack created for your application during execution. Selecting System name: allows you to specify the system name the linker will use to create your application. Pre-defined system names can be found in the file "wlink.lnk" which is located in the "binb" directory of the directory in which you installed WATCOM C/386. Selecting Map file: causes the linker to generate a map file. Once you have chosen to generate a map file, you can specify the name of the map file by selecting Map: . A cursor will appear in the entry field immediately to the right. Simply type the name of the map file. If no file name is specified, the map file will have the same file name as the executable file and file extension "MAP". Selecting Directive file: will place the linker directives used to link your applications in a file. Once you have chosen to generate a linker directive file, you can specify the name of the directive file by selecting Directive: . A cursor will appear in the entry field immediately to the right. Simply type the name of the directive file. If no file name is specified, the directive file will have file name "__WCL__.LNK". Selecting Executable: allows you to specify the name of the executable file generated by the linker. A cursor will appear in the entry field immediately to the right. Simply type the name of the executable file. If no file name is specified, the executable file will have the same file name as the first object file encountered by the linker and extension "EXE". Selecting Additonal linker directives: allows you to specify additional linker directives. ΓòÉΓòÉΓòÉ 11. Application Type ΓòÉΓòÉΓòÉ The dialog entitled Application Type allows you to specify the type of application you are creating. Selecting Build dynamic link library indicates that you are creating a dynamic link library. Special libraries are required to link an application that is a dynamic link library. Selecting Build multi-threaded application indicates that you are creating a multi-threaded application and the multi-threaded version of the libraries should be used to link your application. The run-time libraries contain a default windowing system that allows a character-mode application to display output in a desktop window. The desktop window is not to be confused with a PM compatible window. It is a PM window created using the PM API functions. Selecting Build default-windowed application: causes the default windowing system to be used by your application.