eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ByteCodeCompiler':
Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ByteCodeCompiler

Inheritance:

   Object
   |
   +--Scanner
      |
      +--Parser
         |
         +--ByteCodeCompiler
            |
            +--ByteCodeCompilerWithBreakpointSupport
            |
            +--Decompiler
            |
            +--InstrumentingCompiler
Package:
stx:libcomp
Category:
System-Compiler
Version:
rev: 1.316 date: 2019/05/23 09:09:35
user: cg
file: ByteCodeCompiler.st directory: libcomp
module: stx stc-classLibrary: libcomp
Author:
Claus Gittinger

Description:


This class performs compilation into ByteCodes.
First, parsing is done using superclass methods,
then the parse-tree is converted into an array of symbolic codes
and a relocation table;
these two are finally combined into a byteArray of the codes.

(the intermediate step through symbolic codes is for debugging
 only - it may vanish in future releases)

There are many dependencies to the run-time-system (especially the
interpreter) in here - be careful when playing around ...

[Instance variables:]

    codeBytes       <ByteArry>              bytecodes
    codeIndex       <SmallInteger>          next index to put into code array
    litArray        <OrderedCollection>     literals
    stackDelta      <SmallInteger>          return value of byteCodeFor:
    extra           <Symbol>                return value of byteCodeFor:
    lineno          <Boolean>               return value of byteCodeFor:
    extraLiteral    <Symbol>                return value of byteCodeFor:
    maxStackDepth   <SmallInteger>          stack need of method
    relocList       <Array>                 used temporary for relocation

[Class variables:]

    JumpToAbsJump   <Dictionary>            internal table to map opcodes

    STCCompilationDefines                   passed to stc as command line arguments
    STCCompilationIncludes
    STCCompilationOptions
                    <String>

    STCCompilation  <Symbol>                #always, #primitiveOnly or #never
                                            controls when stc compilation is wanted

    ShareCode       <Boolean>               reuse byteArrays for common (simple) code sequences
                                            This is normally a 'good' optimization,
                                            except if you plan to modify the byteCodes.

Class protocol:

compiling methods
o  compile: methodText forClass: classToCompileFor
compile a source-string for a method in classToCompileFor.
Returns the new method, #Error or nil.

o  compile: aString forClass: aClass inCategory: cat
compile a source-string for a method in classToCompileFor.
The method will get cat as category.
Returns the new method, #Error or nil.

o  compile: aString forClass: aClass inCategory: cat notifying: requestor
compile a source-string for a method in classToCompileFor.
errors are forwarded to requestor.
The method will get cat as category.
Returns the new method, #Error or nil.

o  compile: aString forClass: aClass inCategory: cat notifying: requestor install: install
compile a source-string for a method in classToCompileFor.
The install-argument controls if the method is to be installed into the
classes method-dictionary, or just to be compiled and a method object to be returned.
Errors are forwarded to requestor. The method will get cat as category.
Returns the new method, #Error or nil.

o  compile: aString forClass: aClass inCategory: cat notifying: requestor install: install skipIfSame: skipIfSame
compile a source-string for a method in classToCompileFor.
The install-argument controls if the method is to be installed into the
classes method-dictionary, or just to be compiled and a method object to be returned.
Errors are forwarded to requestor. The method will get cat as category.
If skipIsSame is true, and the source is the same as an existing
methods source, this is a noop (for fast fileIn).
Returns the new method, #Error or nil.

o  compile: aString forClass: aClass inCategory: cat notifying: requestor install: install skipIfSame: skipIfSame silent: silent
compile a source-string for a method in aClass.
errors are forwarded to requestor.
The method will get cat as category.
if install is true, the method is installed in the class.
if skipIfSame, the method is not installed if there is no change
(used when filing in).
if silent is true, no warnings are output.
Returns the new method, #Error or nil.

o  compile: aStringArg forClass: aClassArg inCategory: cat notifying: requestor install: install skipIfSame: skipIfSame silent: silent foldConstants: fold
the basic workhorse method for compiling:
compile a source-string for a method in classToCompileFor.
errors are forwarded to requestor
(report on Transcript and return #Error, if requestor is nil).

The new method will get cat as category.
If install is true, the method will go into the classes method-table,
otherwise the method is simply returned (for anonymous methods).
If skipIsSame is true, and the source is the same as an existing
methods source, this is a noop (for fast fileIn).
The argument, silent controls if errors are to be reported.
Returns the method, #Error or nil.

o  compile: methodText forClass: classToCompileFor install: doInstall
compile a source-string for a method in classToCompileFor.
The install-argument controls if the method is to be installed into the
classes method-dictionary, or just to be compiled and a method object to be returned.
Returns the new method, #Error or nil.

o  compile: methodText forClass: classToCompileFor notifying: requestor
compile a source-string for a method in classToCompileFor.
Errors are forwarded to requestor.
Returns the new method, #Error or nil.

o  compile: textOrStream in: aClass notifying: requestor ifFail: exceptionBlock
name alias for ST-80 compatibility.
Returns the new method, or the value from exceptionBlock.

o  compile: textOrStream in: aClass notifying: requestor install: install ifFail: exceptionBlock
name alias for ST-80 compatibility.
Returns the new method, or the value from exceptionBlock.

o  stcCompileMethod: aMethod

constants
o  byteCodeFor: aSymbol
returns the numeric code for some symbolic bytecodes.

defaults
o  allowExtensionsToPrivateClasses

o  asYetUncategorizedMethodCategory

o  defaultMethodCategory
^ '** As yet uncategorized **'.

initialization
o  initialize
(comment from inherited method)
usually set to true in your .rc file

o  newCodeSet

o  newCodeSet: aBoolean
ByteCodeCompiler newCodeSet:true

o  newPrimitives

o  newPrimitives: aBoolean
ByteCodeCompiler newPrimitives:true

instance creation
o  new
Pretty ugly hack. A caller to compiler may provide a set of breakpoints

private-utilities
o  stringWithSimpleCRs: aString

stc compilation defaults
o  canCreateMachineCode
return true, if compilation to machine code is supported.
Currently, all SYSV4, Linux and WinNT/XP systems do so;
REAL/IX and HPUX9.x do not
(due to the need for dynamic loading of object files, which is not supported by those).
MIPS ULTRIX is almost finished, but not yet released.
(late note - we no longer care for REAL/IX, HPUX9.x and MIPS ULTRIX)

usage example(s): 

     Compiler canCreateMachineCode

o  ccCompilationOptions
return the options used with cc compilation.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  ccCompilationOptions: aString
define the compilation options
to be used when compiling to machine code.
These are passed to cc. Can be set from your private.rc file.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  ccPath
return the path to (name of) the cc command for incremental method compilation.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  ccPath: aPathOrCommandName
set the path to the cc command for incremental method compilation.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilation
return the flag which controls compilation to machine code.
If #always, methods are always compiled to machine code (which takes
longer, but provides faster code). If #none, methods are never compiled
to machine code, instead for non-primitive ones, compilation is to bytecode
and for primitive ones, a trapping stub is generated.
Anything else lets the compiler compile to bytecode,
except for methods containing primitive code.
This can be set from your private.rc file or from a workspace
for selective compilation to machine code.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilation: how
set the flag which controls compilation to machine code.
If #always, methods are always compiled to machine code (which takes
longer, but provides faster code). If #none, methods are never compiled
to machine code, instead for non-primitive ones, compilation is to bytecode
and for primitive ones, a trapping stub is generated.
Anything else lets the compiler compile to bytecode,
except for methods containing primitive code.
This can be set from your private.rc file or from a workspace
for selective compilation to machine code.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilationDefines
return the defines used with stc compilation.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilationDefines: aString
define the flags (for example, additional -D defines)
to be used when compiling to machine code.
These are passed to stc. Can be set from your private.rc file.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilationIncludes
return the includes used with stc compilation.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilationIncludes: aString
define the include directories via additional -I flags.
These are passed to stc. Can be set in your private.rc file.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilationOptions
return the options used with stc compilation.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcCompilationOptions: aString
define the compilation options
to be used when compiling to machine code.
These are passed to stc. Can be set from your private.rc file.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcModulePath
return the path, where temporary modules are created.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcModulePath: aPath
set the path to the directory, where temporary modules are created.
Obsolete; knowledge moved to parserFlags,
where it is also obsolete now, as this should not be set from the outside,
but instead rely totally on the userPreferences.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcPath
return the path to the stc command, or nil if not found.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcPath: aPath
set the path to the stc command - useful if private stc is wanted.
This method remains here for backward compatibility (older script files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  stcPathOf: command
return the path to an stc command, or nil if not found.

usage example(s): 

     Compiler stcPathOf:'stc'

Instance protocol:

Compatibility-ST80
o  compile: textOrStream in: aClass notifying: requestor ifFail: exceptionBlock
name alias for ST-80 compatibility

o  compile: textOrStream in: aClass notifying: requestor install: install ifFail: exceptionBlock
name alias for ST-80 compatibility

o  from: aStream class: aClass context: ctx notifying: aRequestor

accessing
o  code
return the bytecode array - only valid after code-generation

o  literalArray
return the literal array - only valid after parsing

o  maxStackDepth
return the stack-need of the method - only valid after code-generation

o  methodClass

o  methodClass: aClass

code generation
o  byteCodeFor: aSymbol
given a symbolic instruction, return the corresponding bytecode.
as a side-effect, leave number of bytes pushed/popped by this instr.
in stackDelta, and, if the instruction needs extra arguments, leave
this info in extra. Also lineno is set to true, if this code has line
information and extraLiteral is set if any hidden send is performed by it.

o  checkForCommonCode: symbolicCodeArray
hook to return the code for common code sequences.
This reduces the in-memory number of byteArrays somewhat.

Not yet fully implemented - just an idea ... there is certainly more to do here
(does it make sense to scan all methods, collect code in a set and unify things
automatically in the background - or upon request ?)

o  checkForPrimitiveCode: nr
return the code for an ST-80 primitive method.
Since many primitives available on ST-80 should also be available
somewhere in ST/X, this may work for many primitive numbers.
However, more information is needed and more things to be added below.

This was added to allow emulation of (some) ST-80
primitives (to fileIn RemoteInvocation & Monitor41 packages)

o  codeLineNumber: nr on: codeStream
generate lineNumber information

o  createMethod
fixup CheapBlocks method-field in literal array,

o  genByteCodeFrom: symbolicCodeArray
convert symbolicCode into bytecodes

o  genSpecialStatement: selector on: codeStream
generate: thisContext selector (to force a context).

o  genSymbolicCode
traverse the parse-tree producing symbolicCode - return the codeArray

o  generateVariables: varCollection on: codeStream
generate code to set it up.

o  relocateWith: symbolicCodeArray relocInfo: relocInfo
helper for genByteCodeFrom - relocate code using relocInfo.
if relocation fails badly (due to long relative jumps) patch
symbolicCode to use absolute jumps instead and return false
(genByteCodeFrom will then try again). Otherwise return true.
Also, on the fly, jumps to jumps and jumps to return are handled.

code generation helpers
o  absJumpFromJump: code
given a jump-symbolic code, return corresponding absolute jump

o  addLiteral: anObject
add a literal to the literalArray - watch for and eliminate
duplicates. return the index of the literal in the Array

o  addReloc: symIndex
remember to relocate offset at symIndex later ...

o  addTempVar
add a temporary variable; return its position (1-based).
Used when a block with args/locals is inlined.

o  appendByte: aByte
append a byte to the code-Array, checking for byte-range (debug-only)

o  appendByteCodeFor: codeSymbol
append the byteCode for an instructionSymbol to the code-Array

o  appendEmptyByte
append an empty byte to the code-Array

o  appendEmptyLong
append an empty long (4 bytes) to the code-Array

o  appendEmptyShort
append an empty short (2 bytes) to the code-Array

o  appendLongWord: aWord
append an unsigned long word (low-high) to the code-Array,
checking for long word-range (debug-only)

o  appendSignedByte: aByte
append a signedbyte (as in jump-offsets) to the code-Array,
check range and report an error if invalid

o  appendSignedWord: aWord
append a signed word to the code-Array,
check range and report an error if invalid

o  appendWord: aWord
append an unsigned word (low-high) to the code-Array,
checking for word-range (debug-only)

o  nameSpaceSelectorFor: aSymbol
Caring for the current namespace, return the real selector used for a send.

o  removeTempVar
remove a temporary variable

code generation hooks
o  startCodeGenerationHookOn: codeStream
invoked before code is generated;
gives subclasses a chance to prepare and to inject code to be
executed on entry (instrumentation)

compilation
o  compile: aString forClass: aClass inCategory: cat
compile a source-string for a method in classToCompileFor.
The method will get cat as category.
Returns the new method, #Error or nil.

o  compile: aStringArg forClass: aClassArg inCategory: cat notifying: aRequestor install: install skipIfSame: skipIfSame silent: silent foldConstants: fold
if proceeded, install a trap method

o  compile: sourceCodeStringArg forClass: aClassArg inCategory: cat notifying: aRequestor install: install skipIfSame: skipIfSame silent: silent foldConstants: fold ifFail: failBlock
the basic workhorse method for compiling:
compile a source-string for a method in classToCompileFor.
errors are forwarded to requestor
(report on Transcript and return the value of failBlock, if requestor is nil).

The new method will get cat as category.
If install is true, the method will go into the classes method-table,
otherwise the method is simply returned (for anonymous methods).
If skipIsSame is true, and the source is the same as an existing
methods source, this is a noop (for fast fileIn).
The argument, silent controls if errors are to be reported.
Returns the method, #Error or nil.

o  compile: methodText forClass: aBehavior install: doInstall
compile a source-string for a method in classToCompileFor.
The install-argument controls if the method is to be installed into the
classes method-dictionary, or just to be compiled and a method object to be returned.
Returns the new method, #Error or nil.

o  compileTree: aTree forClass: aClass
given an already parsed AST, generate code and return a method

o  compileTree: aMethodNode forClass: aClass ifFail: failBlock
given an already parsed AST, generate code and return a method

o  showErrorNotification: message

error handling
o  codeGeneratorError: aMessage

machine code generation
o  trappingStubMethodFor: aString inCategory: cat
return a stub method which traps and reports an error whenever
called.

queries
o  hasLineNumber: sel
return true, if special send code needs lineNr

o  isBuiltInSelector: sel forReceiver: receiver
return true, if selector sel is built-in.
(i.e. there is a single bytecode for it)

o  isCompiling
return true if compiling code as opposed to evaluating

o  numberOfTempVars
return the number of additional temporary variables which
were created from inlined blocks (valid after parsing)

o  specialGlobalCodeFor: aSymbol
codeExtension for globals,
which can be accessed by specialGlobal opCode

o  specialGlobals
list of globals which can be accessed by specialGlobal opCode;
adding any here requires a new VM (i.e. you cannot change it)

o  specialSendCodeFor: sel
return the codeExtension for sends,
which can be performed by specialSend opCode

o  specialSends
list of selectors which can be sent by specialSend opCode;
adding any here requires a new VM (i.e. you cannot change it)

Examples:


a GNU-Smalltalk method: 
Compiler
    compile:'bla
<category: ''tests''>

^ 123
'
    forClass: Object

ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Sat, 20 Apr 2024 10:54:23 GMT