Programmer's Guide

somFree compiler is a tool to convert various interface definition languages to another one or language bindings. somFree compiler frontend is a sc or somc command which control workflow. Because somFree compiler and Emitter Framework modeled after IBM SOM Compiler from here SOM Compiler term will be used. Most of somFree Compiler and Emitter Framework and SOM Compiler and Emitter Framework are same and binary compatible at the documented level. Internal structures of somFree and IBM versions are different.

SOM Compiler at file level consist of:

• SOM Compiler frontend
  • sc [Linux]
  • sc.exe [OS/2, Windows]
  • somc.exe [Windows]
• IDL SOM Pre-processor
  • somcpp [Linux]
  • somcpp.exe [OS/2, Windows]
• IDL SOM Compiler
  • somipc [Linux]
  • somipc.exe [OS/2, Windows]
• OIDL SOM Pre-processor
  • spp [Linux]
  • spp.exe [OS/2, Windows]
• OIDL SOM Compiler
  • somopc [Linux]
  • somopc.exe [OS/2, Windows]
• SOM Compiler Library
  • somc.so [Linux]
  • somc.dll [OS/2, Windows]
• SOM Emitter Framework
  • some.so [Linux]
  • some.dll [OS/2, Windows]
• Emitters
  • emit*.so [Linux]
  • emit*.dll [OS/2, Windows]
• Public IDL files generator
  • pdl [Linux]
  • pdl.exe [OS/2, Windows]

Currently SOM Compiler provides following emitters:

• IDL - IDL Emitter
• CSC - OIDL Emitter
• SC - OIDL public emitter
• GEN - Generic Emitter
• IR - Interface Repository Emitter
• H - C Binding public header files
• C - C Binding implementation template file
• IH - C Binding implementation header files
• XH - C++ Binding public header files
• XIH - C++ Binding implementation header files
• DEF - DEF Module Definition file
• LNK - LNK Module Linking file
• HC
• IMOD - SOM Module initialization emitter
• MODS - List of class modifiers
• PDL - Private IDL emitter
• PH
• PSC - OIDL private emitter
• UC
• UXC
• XPH
• XTM
• PAS - Pascal client library for use of SOM
• IPAS - Pascal implementation library to write SOM classes.

Some of Emitters uses Templates such as:

• cpp.efw
• ctm.efw
• gen_c.efc
• gen_c.efs
• gen_c.efw
• gen_cpp.efw
• gen_def.efw
• gen_emit.efc
• gen_emit.efs
• gen_emit.efw
• gen_emit.efx
• gen_idl.efw
• gen_make.efc
• gen_make.efs
• gen_make.efw
• gen_make.efx
• gen_mk32.efc
• gen_mk32.efs
• gen_mk32.efw
• gen_mk32.efx
• gen_mknt.efs
• gen_mknt.efw
• gen_mknt.efx
• gen_nid.efw
• gen_temp.efw
• imod.efw

Emitter Framework is a set of classes and SOM Compiler tool. Emitter Framework is used to produce various file formats from the SOM Interface Definition Language files. Emitter Framework classes consist of Emitter classes and Entry classes. Classes can be shadowed. This means a programmer can replace original classes with his own classes. So the SOM Compiler can be highly customized. The only things hard-coded (and closed source) are the IDL file reader and abstract graph builder.

Before starting description of Emitter Framework let's talk about SOM Compiler. We already talked briefly about SOM Compiler. But for emitters we need to know internals of SOM Compiler much better.

Let's start from visible parts of SOM Compiler that requires for its work the following files:

• sc.exe, somc.dll and somc.msg - Main part of compiler.
• somcpp.exe - SOM Preprocessor
• somipc.exe - Goals not known. Seems just execute different emitters
• emit*.dll - Emitters
• *.efw - Emitter templates

sc.exe is general part of compiler. Let's try to investigate some internals of sc.exe. First of all we can switch on verbose output and look on it:

Running shell command:
somcpp -D__OS2__  -I. -IC:\os2tk45\h -IC:\os2tk45\idl -IC:\os2tk45\som\include \
      -D__SOMIDL_VERSION_1__ -D__SOMIDL__ -C somobj.idl > C:\var\temp\0a500000.CTN
somipc -mppfile=C:\var\temp\0a500000.CTN -v -e emith -e emitih -e emitctm -e emitc \
      -o somobj somobj.idl
Loading  emith.
"SOMObject"
Unloading  emith.
Loading  emitih.
"SOMObject"
Unloading  emitih.
Loading  emitctm.
"SOMObject"
Unloading  emitctm.
Loading  emitc.
"SOMObject"
Unloading  emitc.
Removed "C:\var\temp\0a500000.CTN".

Not so many info, but some information here. If we look at SMINCLUDE environment variable:

SMINCLUDE=.;C:\os2tk45\h;C:\os2tk45\idl;C:\os2tk45\som\include;

then we will see all paths in -I option.

Considering -D is same as for CPP we can see three symbols defined: * OS2 * SOMIDL_VERSION_1 * SOMIDL somobj.idl it is file we emitted and CTN file is output from preprocessor. The only unknown switch is -C. After small playing we can see it means “leave comments”.

So, we can try to replace somcpp with some preprocessor. In [http://www.osfree.org osFree] project we tried to use [http://mcpp.sourceforge.net MCPP] preprocessor. Results is well.

sc.exe reads SMINCLUDE variable and puts its content to -I options of somcpp.exe and redirect output to temporary file.

Ok. Now we can try to detect what is somipc.exe. If we try to execute it with command line pointed above, then we will see: Loading emith. “SOMObject” Unloading emith. Loading emitih. “SOMObject” Unloading emitih. Loading emitctm. “SOMObject” Unloading emitctm. Loading emitc. “SOMObject” Unloading emitc.

Heh. Actually, somipc.exe is a real SOM Compiler. Not sc.exe. sc.exe only prepares the input file for the compiler and handles command line and environment variables.

After some playing we can see, somipc returns 0 if all ok and -1 if error.

So, somipc.exe parses preprocessed IDL file and builds Abstract graph. From Abstract graph Object Graph are build. After this somipc.exe calls one by one all emit*.dll files according to -e switches. emit*.dll are set of DLLs with SOM classes.

Drawing here!!

SOM Compiler IDL SOM Preprocessor IDL SOM Compiler Emitter Template

		OIDL SOM Preprocessor	OIDL SOM Compiler

Разрисовать по аналогии с со структурой, что в патентах и документации по SOM, но с учетом наличия OIDL и SOMC.

SOM Compiler sc or somc is a frontend which controls basic workflow. Depending on source file extension it call or IDL or OIDL pre-processor and, after preprocessing, IDL or OIDL compiler. IDL or OIDL compiler builds abstract syntax graph using Entry structure. Entry structure contains information about entry type, pointer to object wrapper and all information about object specific attributes.

Note! Entry structure is not documented and differs in somFree and IBM SOM versions.

IDL or OIDL calls required emitters with root Entry structure on emitter entry. Emitter requests root object wrapper and, using or not using template faculty, process all graph using Object Syntax Graph. Object Syntax Graph generates required Entry objects on demand.

Emitter is a subclass of 'SOMTEmitC' class. Emitter used to produce output file using template file from object graph of the SOM Interface Definition Language file. Physically emitter represented as DLL with name EMIT<identificator>.DLL. For C headers emith.dll emitter DLL is used. For C++ headers emitxh.dll emitter DLL is used. Emitter DLL contains only one entry with ordinal 1 and name 'emit'.

SOMEXTERN FILE * SOMLINK emit(char *file, Entry * cls, Stab * stab);

'emit' function creates emitter object (from emitter class, which based on 'SOMTEmitC') and calls 'somtGenerateSections' method.

Usually an emitter file can be generated using 'newemit.cmd' script (can be found at Hobbes in SOMObjects toolkit).

newemit -C <className> <file_stem>

To emitter passed Entry object which is root of Object Graph. The root object can be an interface or module class. Processing of such classes slightly different.

Last part of Emitter Framework is template files. Template files allow you to make some control of emitting process. Templates are usual text files with extension *.efw. Here you can modify output for your wish. Not all emitters support templates.

So, now you have some imagination about that Emitter Framework is and how it works.

Emitters uses template faculty to produce output file. Template file has structure divided by sections. Each section begins from section name ended by colon. Each emitter can use its own section names. Refer to corresponding emitter and Entry classes description for section names information. Here is template file example:

:copyrightS
This is example template
:templateS
/* Template output example */
<className>

Core of Template faculty is a Key-Value strings collection represented by SOMStringTableC class. All substitutable to template values stored in SOMStringTableC class instance. On template file process, First of all SOMTEmitC method somtSetPredefinedSymbols sets section names symbols. By default it is following sections:

Generic emitter is a generic template based emitter. It uses simplest template with only one section “template”. Main goal of Generic Emitter is to produce Generic framework emitter files. It is used by newemit tool to produce full set of files required to build new emitter. Добавить описание символов шаблона и описание, какой шаблон за что отвечает.

DEF emitter used to generate definition file for DLL creation using MS LINK. somFree version of emitter uses template file to generate DEF file. Original IBM SOM DEF Emitter uses hard coded generation. Добавить описание символов шаблона.

LNK emitter used to generate linking file for DLL creation using Watcom WLINK. somFree version of emitter uses template file to generate LNK file. Original IBM SOM DEF Emitter doesn't have such emitter. Добавить описание символов шаблона.

CSC emitter used to generate OIDL class definition file (CSC) used in IBM SOM 1.0. somFree version of emitter uses template file to generate CSC file. Original IBM SOM CSC Emitter uses hard coded generation. Добавить описание символов шаблона.

IDL emitter used to generate IDL class definition file used in IBM SOM 2.0 and higher. somFree version of emitter uses template file to generate IDL file. Original IBM SOM IDL Emitter uses hard coded generation. Добавить описание символов шаблона.

somFree Emitter Framework provides templates and libraries for developing emitters compatible with both IBM SOM 2.1 and IBM SOM 3.0 compilers. Because of different ABI (refer Appendix 1 for more information) somFree emitters automatically configures for corresponding API.

somFree Compiler support CORBA C Language Mapping Specification 1.0 [1]. CORBA C Language mapping slightly differ from SOM C Language mapping, used by original IBM SOM 2.1. CORBA C Language mapping is default for somFree Compiler. This chapter provides short description of mapping. For full description refer to [1].

SOM C Language mapping is a IBM SOM mapping variant. For some reason (most probably because variable arguments support) IBM SOM not exactly implements C Language Mapping Specification.