ACE

From Liberty Eiffel Wiki
Revision as of 02:47, 22 June 2016 by Dkearns (talk | contribs) (s/no_style_warning/style_warning/)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search 
 * This page needs checking for accuracy and completeness.
 * safety_check (yes) needs to be documented

ACE File

An ACE file defines the environment for a project, together with its root class and initial creation procedure.

Use of an ACE file obviates the need for specifying many options on the command line and ensures consistency between successive compilations or other operations on the project. Such consistency makes it easier to test and debug, since changes from one compilation to the next are guaranteed to be limited to coding changes rather than to changes in the compilation environment.

Naming

An ace file must have a name ending with the suffix .ace.

Structure of the ACE file

The file is divided into sections, each introduced by a keyword. These are conventionally presented in an order laid out in the template ACE file, which is found under the Liberty Eiffel directory tutorial/ace/. These sections are: system, root, default, cluster, external and generate.

System section

The system section is introduced by the keyword system followed by the name to be given to the executable program which will be produced by a compilation. The system name should be enclosed in double quotes.

Example: 

 system
  
    "my_system"

Root section

The root section defines the root class of the system and the initial creation procedure. The creation procedure is the routine which is executed first when the executable program is run; it is equivalent to main() in a C program. This procedure must be a procedure in the root class and must be declared as a creation procedure in that class.

Example: 

 root
  
    MY_SYSTEM: make

Here MY_SYSTEM is the root class and make is the initial creation procedure.

Default section

The default section defines the defaults which will apply to the whole compilation unless overridden for specific sections. It is introduced by the keyword default.

Within the default section are listed various defaults and their settings. If any default is unlisted, it takes its value from the defaults compiled into Liberty Eiffel when it was installed.

The syntax for setting a default is: 

  setting_name (setting);

Do not forget the terminating semi-colon.

These are the settings which may be included in the default section:

  • assertion

This specifies the default level of assertion checking for the system. Choose the appropriate value as explained in the description of compile_to_c: boost, no, require, ensure, invariant, loop, check or all.

  • assertion_flat_check

In flat mode each assertion will be executed in no_check mode. This means that while an assertion is being checked, no other assertion will be checked. This mode is only meaningful in assertion modes from require to debug. The possible values for this setting are yes or no.

  • debug

This is the default debug level for the system. Choose yes, no, or any "key" you wish. When debugging is turned on, debug sections in the source code are enabled.

  • trace

This is the default trace mode for the system. Choose yes or no. When tracing is turned on, the sedb debugger is enabled when the executable is run.

  • collect

Choose "bdw" here to add the Boehm-Demers-Weiser conservative collector linked into to your system. Choose yes here to add the native garbage collector support to your system. Choose no here to indicate that you don't want the garbage collector to be included in your system; no is the equivalent of the -no-gc flag in traditional command line mode. See Garbage collector for details.

  • style_warning

If set to no, this will suppress the display of warning messages about non-compliance with Eiffel style rules (for example, ItEm will not trigger a message). The Liberty Eiffel Team's recommendation is that you should always set this to yes. This setting is the equivalent of the -style_warning flag in traditional command line mode.

  • no_warning

If set to yes, this will suppress all warning messages. The Liberty Eiffel Team's recommendation is that you should always set this to no. Yes is the equivalent of the -no_warning flag in traditional command line mode.

  • verbose

Set to yes to display (an enormous amount of) information during compilation: a complete trace of files loaded, type inference scores, generated files and so on. This is the equivalent of the -verbose flag in traditional command line mode. (Note too that the -verbose flag is still accepted in ACE file mode.)

  • manifest_string_trace

Set to yes to include in your executable a trace of the creation of manifest strings. This can be useful for tracking down some memory errors. This is the equivalent of the -manifest_string_trace flag in traditional command line mode.

  • high_memory_compiler

When set to yes, this allows the compiler to use more memory. This can allow faster compilation, if you have enough RAM. This is the equivalent of the -high_memory_compiler flag in traditional command line mode.

  • profile

When set to yes, this allows you to include the profiler in your executable. This is the equivalent of the -profile flag in traditional command line mode.

  • relax

This is the equivalent of the -relax flag in traditional command line mode. [What the -relax flag actually does is not documented.]

Example: 

 default
  
   assertion (require);
  
   assertion_flat_check (no);
  
   debug (no);
  
   trace (no);
  
   collect (yes);
  
   no_style_warning (no);
  
   no_warning (no);
  
   verbose (no);
  
   manifest_string_trace (yes);
  
   high_memory_compiler (no);
  
   profile (yes);
  
   relax (yes);
  

Cluster section

The cluster section is introduced by the keyword cluster and defines an ordered list of clusters. Roughly speaking, a cluster can be considered as a directory in which Eiffel source files are to be searched for. The order of this list of clusters is important because clusters are considered sequentially when searching for an Eiffel source file. The first class file found in the search is the one that will be used.

Each cluster is described as follows: 

  optional_cluster_name: "cluster_path_using_system_file_notation_here"
     default -- at this cluster level
        assertion (require)
        debug (no);
        trace (no);
     option -- for this cluster
        assertion (loop) : CLASS_NAME1, CLASS_NAME2;
        assertion (all)  : CLASS_NAME3, CLASS_NAME4;
        -- ...
        debug (yes) : CLASS_NAME1, CLASS_NAME2, ...;
        debug ("KEY") : CLASS_NAME1, CLASS_NAME2, ...;
        -- ...
        trace : CLASS_NAME1, CLASS_NAME2;
        trace : CLASS_NAME3, CLASS_NAME4;
        -- ...
     end -- of one cluster

The default subsection is used to set defaults that apply only to classes from this particular cluster. The settings that may be used are assertion, debug and trace.

The option subsection is used to modify the cluster or system defaults for particular classes in the cluster

The following cluster definition can be used, after all the other cluster definitions, to pull in Liberty Eiffel's standard library. Always put this last so that you can override options for parts of the standard library by writing your own replacement class files and placing them in earlier clusters. 

  standard: "${path_lib}/loadpath.se"

Example: 

 cluster
  
   utilities: "../../utilities"
     default
        assertion (all)
        debug (yes);
        trace (no);
   end
  
   utilities_se: "../../utilities/se"
     default
        assertion (all)
        debug (no);
        trace (yes);
   end
  
   dbmap: "../../system/dbmap"
     default
        assertion (all)
        debug (no);
        trace (no);
     option
        trace : JOB_DB_MAP, PURCHASED_JOB_DB_MAP;
   end
  
   egtk: "${EGTK}/lib/glib";end
  
   standard: "${path_lib}/loadpath.se"

Notice that when the trace option is used in relation to a particular class, the setting is always turned on; the setting value is not specified.

External section

The next section is introduced by the keyword external; it defines how the C code generated from the Eiffel classes is to be linked with system libraries and code written in other languages to make a complete executable.

The external section contains the following settings:

  • external_header_path

This is a space-separated list of directories to be searched for C include files (which typically have .h as a suffix).

  • external_object_files

This is a space-separated list of the path names of object modules to be linked into the executable. These are files output by a C compiler with the suffix .o.

  • external_c_files

This is a space-separated list of C source files which need to be compiled and whose object modules will be linked into the executable.

  • external_c_plus_plus_files

This is a space-separated list of C++ source files which need to be compiled and whose object modules will be linked into the executable.

  • cecil ("my_cecil_file1.se")

This line appears once for each Cecil file that is to be included in the build (see cecil for details).

  • external_lib_path

A space separated list of directories which are to be searched for system libraries. On a Unix system a directory name may optionally be prefixed by -L (this used to be required before release -0,74 of SmallEiffel).

  • external_lib

A list of libraries to be supplied to the linker. The lib prefix of the library name is always omitted; the prefix -l may optionally be used for each library. Other linker options can be included.

Example (abridged for convenient display): 

 external
    
   external_object_files: "/usr/local/lib/libutils.a /usr/local/libeifpq.a"
    
   external_header_path: "/usr/include/gtk-1.2 /usr/include/gdk-1.2 -I. "
    
   external_c_files: "/usr/local/src/eif_gtk_se.c"
    
   cecil ("/usr/local/src/cecil.se")
    
   external_lib_path: " -L/usr/lib/debug -L/usr/X11R6/lib"
    
   external_lib: "-rdynamic -lpq -lgnomeui -lart_lgpl -lX11 -lm"


Generate section

This section, introduced by the keyword generate, controls the generation of C code by compile_to_c.

The section contains the following possible settings:

  • no_strip

When set to yes, this suppresses the running of strip on the generated executable. This is the equivalent of the -no_strip flag of the traditional command line mode. (If you want to use a C level debugger on your system, you should choose yes here).

  • no_split

When set to yes, this causes compile_to_c to produce a single, large C file for the entire system, instead of the many small C files produced by default (when this is set to no). This setting may be useful for delivery of the most efficient version. (Some C compilers, including gcc, can then do better inlining.)

  • clean

When set to yes, this makes the compiler remove all generated C files, all generated object files and other temporary files generated during the compilation process. (See the command clean.) This ensures that all code is freshly generated and compiled, but will extend the time needed for recompilation.

  • cc

The equivalent of the -cc flag of the traditional command line mode. This defaults to the value, gcc. To select a different C compiler from the default, set the option to the appropriate system command.

  • c_compiler_options

Use this keyword to supply additional options to be passed to the C compiler, to control optimisation or the production of debugging symbols, for example.

  • linker_options

This option can be used to set compiler options that are to be passed only to the linker.

  • no_main

Set this to yes to suppress the generation of a main() C code routine. This is used for generating object libraries.

  • gc_info

When this option is set to yes, the garbage collector displays at run time some information about its use.

  • wedit

To Include support for the Wedit debugger, set this option to yes.

Example: 

 generate -- section
    
   no_strip(yes);
    
   no_split(no);
    
   clean(no);
    
   c_compiler_options : "-Wall -g -pipe -DNEED_GNOMESUPPORT_H "
    

Variables

As in the cluster and external section examples above, environmental variables can be used to save typing (and also to enable a whole directory tree to be moved at the cost only of redefining the variable rather than rewriting every ace file.

A variable is referenced by the construct ${variable_name}.

Some variables are defined in the system configuration file (e.g. /etc/liberty-eiffel/liberty.se); such are the variables ${path_lib} and ${path_tutorial}. Other variables can be set and exported in the system environment, as, for example, by the Bourne shell command: 

 $ export EGTK=/usr/local/lib/egtk

Using an ACE file

An ACE file may be used by specifying it immediately after the command which is to use it, before any other options to that command.

For example: 

 se compile my_system.ace
  
 se short my_system.ace my_system
  
 se finder my_system.ace some_class


ACE syntax checking

The syntax of an ACE file may be checked by the ace_check command.

This command will report any errors and will also expand any loadpath.se files that are included in the ACE file and list each component directory.

Example: 

 se ace_check my_system.ace

Retrieved from "https://wiki.liberty-eiffel.org/index.php?title=ACE&oldid=2497"