<!doctype html public "-//W3C//DTD W3 HTML//EN">
<html><head><style type="text/css"><!--
blockquote, dl, ul, ol, li { padding-top: 0 ; padding-bottom: 0 }
--></style><title>V2.3 Plugin Modules are Sweet!</title></head><body>
<div>Since I couldn't get 2.3 to compile cleanly under MPW and MrC
:-(, I've been messing around instead with the plugin named primitive
facilities. Its winning, IMHO.</div>
<div><br></div>
<div>Since there isn't much documentation, except for the examples in
Squeak-Plugins, I offer the following. One caveat: I am
super-newbie without documentation, so please forgive any blatant
blunders. </div>
<div><br></div>
<div>Although the following has a Macintosh gloss, the beauty of the
Squeak code generation architecture is such that these notes should be
useful for most any platform.</div>
<div><br></div>
<div>THE PLAN:</div>
<div><br></div>
<div>As an existence proof that this thing works, I set out to create
four simple test primitives that do the following:</div>
<div><br></div>
<div><x-tab> </x-tab>*
answer an integer constant (I chose 17, per Alan Demers)</div>
<div><x-tab> </x-tab>*
answer an integer parameter passed therein</div>
<div><x-tab> </x-tab>*
answer the sum of two integer parameters</div>
<div><x-tab> </x-tab>*
answer the sum of an integer parameter and an instance var</div>
<div><br></div>
<div>I figured if I could get that going, I was well on my way to
making a true mess of things. I made no effort to bulletproof
these prims, just getting them 'working' was my sole goal.</div>
<div><br></div>
<div>----------</div>
<div><br></div>
<div>STEP ONE: BUILD THE SMALLTALK CLASSES:</div>
<div><br></div>
<div>I created a class that will contain the Squeak plugin module
code, and aptly named it "FooPlugin," making the class a
subclass of InterpreterPlugin class:</div>
<div><br></div>
<div><x-tab>
</x-tab>InterpreterPlugin subclass: #FooPlugin</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>instanceVariableNames: ''</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>classVariableNames: ''</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>poolDictionaries: ''</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>category: 'Werdna-Foostuff'</div>
<div><br></div>
<div>I then created a class to call and demonstrate the plugin
primitives, aptly named it "Foo", with a single instance
variable named myInteger:</div>
<div><br></div>
<div><x-tab> </x-tab>Object
subclass: #Foo</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>instanceVariableNames: 'myInteger '</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>classVariableNames: ''</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>poolDictionaries: ''</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>category: 'Werdna-Foostuff'</div>
<div><br></div>
<div><br></div>
<div>--------- </div>
<div><br></div>
<div>STEP TWO: BUILD THE SMALLTALK INTERFACE IN FOO:</div>
<div><br></div>
<div>Then I added an accessor for myInteger:</div>
<div><br></div>
<div><x-tab>
</x-tab><b>myInteger: anInteger</b></div>
<div><b><x-tab>
</x-tab><x-tab>
</x-tab></b>"setter: set myInteger to anInteger"</div>
<div><br></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>^myInteger _ anInteger</div>
<div><br></div>
<div>And wrote the four primitive calling procedures:</div>
<div><br></div>
<div><x-tab>
</x-tab><b>integerSeventeen</b></div>
<div><b><x-tab>
</x-tab><x-tab>
</x-tab></b>"answer the constant value 17"</div>
<div><x-tab> </x-tab></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab><primitive: 'primFooIntegerSeventeen' module:
'Foo'></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>^FooPlugin doPrimitive: 'primFooIntegerSeventeen'</div>
<div><br></div>
<div><br></div>
<div><x-tab>
</x-tab><b>integerIdentity: anInteger</b></div>
<div><b><x-tab>
</x-tab><x-tab>
</x-tab></b>"answer anInteger"</div>
<div><br></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab><primitive: 'primFooIntegerIdentity' module:
'Foo'></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>^FooPlugin doPrimitive:
'primFooIntegerIdentity'<x-tab>
</x-tab></div>
<div><br></div>
<div><br></div>
<div><x-tab>
</x-tab><b>integerSum: firstInteger and: secondInteger</b></div>
<div><b><x-tab>
</x-tab><x-tab>
</x-tab></b>"answer the sum of firstInteger and
secondInteger"</div>
<div><br></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab><primitive: 'primFooIntegerSumAnd' module: 'Foo'></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>^FooPlugin doPrimitive: 'primFooIntegerSumAnd'</div>
<div><br></div>
<div><br></div>
<div><x-tab>
</x-tab><b>integerSumWith: anInteger</b></div>
<div><b><x-tab>
</x-tab><x-tab>
</x-tab></b>"answer the sum of anInteger and self
myInteger"</div>
<div><br></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab><primitive: 'primFooIntegerSumWith' module: 'Foo'></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>^FooPlugin doPrimitive: 'primFooIntegerSumWith'</div>
<div><br></div>
<div>A few remarks. The syntax:</div>
<div><br></div>
<div><x-tab>
</x-tab><primitive: 'primitiveName' module: 'moduleName'></div>
<div><br></div>
<div>directs Squeak to try to find exported function primitiveName in
dynamic library moduleName. Since neither the library nor the
primitives exist as of yet, these primitive calls will ALWAYS fail.
A failing primitive then "falls through" to execute the
subsequent Smalltalk code. Now, the next lines of each routine
call an inherited method of FooPlugin, doPrimitive, which will run an
interpreter on the Smalltalk code as we develop it.</div>
<div><br></div>
<div>In other words, if the module and method are found and the
machine code executes cleanly, it returns without more.
Otherwise, the next line is executed, which directly interprets the
Smalltalk bytecodes in FooPlugin, even if the module has not yet been
completed.</div>
<div><br></div>
<div>It's that EASY! And that's the point -- we can now build
our primitives in Squeak, test them in Squeak, and later, when we are
happy with the code, we can then go to the big bad compiler and try to
install the module itself.</div>
<div><br></div>
<div>STEP THREE: BUILD THE PRIMITIVES IN FOOPLUGIN:</div>
<div><br></div>
<div>The following methods live in FooPlugin. The code for
integerSeventeen:</div>
<div><br></div>
<div>primFooIntegerSeventeen</div>
<div><x-tab>
</x-tab>"primitive answering constant (int) 17"</div>
<div><br></div>
<div><x-tab> </x-tab>self
export: true. "this tells the translator that </div>
<div><x-tab>
</x-tab><x-tab> </x-tab>this
is a public primitive function"</div>
<div><x-tab> </x-tab>self
inline: false. "this tells the translator not </div>
<div><x-tab>
</x-tab><x-tab> </x-tab>to
bother inlining messages"</div>
<div><x-tab>
</x-tab>interpreterProxy pop: 1. "pop the top of stack (the
receiver)"</div>
<div><x-tab>
</x-tab>interpreterProxy pushInteger: 17. "push the return
value"</div>
<div><br></div>
<div><br></div>
<div>We use interpreterProxy, which is an instance of
InterpreterProxy, to manipulate the Squeak VM, which we need in order
to get parameters and instance variables; push answers on the stack
for returning and the like. The first two pseudo-calls teach the
compiler how to generate the code, in particular, making sure the
primitive will be externally callable and telling it not to bother
inlining subroutines (which we don't use in these examples).
When a primitive without parameters gets control, the receiver is on
the top of the stack. For this routine, we simply pop it, push
the constant, and we are finished with our work. The other
routines follow:</div>
<div><br></div>
<div>primFooIntegerIdentity ": anInteger"</div>
<div><x-tab>
</x-tab>"primitive answering first (int) parameter"</div>
<div><br></div>
<div><x-tab>
</x-tab>|anInteger|</div>
<div><x-tab> </x-tab>self
export: true.</div>
<div><x-tab> </x-tab>self
inline: false.</div>
<div><x-tab>
</x-tab>anInteger _ interpreterProxy stackIntegerValue: 0.</div>
<div><x-tab>
</x-tab>interpreterProxy pop: 2.</div>
<div><x-tab>
</x-tab>interpreterProxy pushInteger: anInteger.</div>
<div><br></div>
<div>Here, the stack holds both the parameter and the receiver
pointer. We use the zero-indexed method stackIntegerValue to
pull down the parameter, clear the stack, and push the result.</div>
<div><br></div>
<div>primFooIntegerSumAnd ":firstInteger and:
secondInteger"</div>
<div><x-tab>
</x-tab>"answer sum of (int) firstInteger and (int)
secondInteger"</div>
<div><br></div>
<div><x-tab>
</x-tab>|firstInteger secondInteger|</div>
<div><x-tab> </x-tab>self
export: true.</div>
<div><x-tab> </x-tab>self
inline: false.</div>
<div><x-tab>
</x-tab>secondInteger _ interpreterProxy stackIntegerValue: 0.</div>
<div><x-tab>
</x-tab>firstInteger _ interpreterProxy stackIntegerValue: 1.</div>
<div><x-tab>
</x-tab>interpreterProxy pop: 3.</div>
<div><x-tab>
</x-tab>interpreterProxy pushInteger:
(firstInteger+secondInteger).</div>
<div><br></div>
<div>Same deal, except we get two parameters instead of one.
(remember to pop the receiver as well), and then push the sum.</div>
<div><br></div>
<div>primFooIntegerSumWith ": anInteger"</div>
<div><x-tab>
</x-tab>"answer the sum of my (int) parameter and (int) first
instance var"</div>
<div><x-tab>
</x-tab>"No type checking done, I simply assume the field is an
integer"</div>
<div><br></div>
<div><x-tab>
</x-tab>|anInteger rcvr myInteger |</div>
<div><x-tab> </x-tab>self
export: true.</div>
<div><x-tab> </x-tab>self
inline: false.</div>
<div><x-tab>
</x-tab>anInteger _ interpreterProxy stackIntegerValue: 0.</div>
<div><x-tab> </x-tab>rcvr _
interpreterProxy stackObjectValue: 1.</div>
<div><x-tab>
</x-tab>myInteger _ interpreterProxy fetchInteger: 0 ofObject:
rcvr.</div>
<div><x-tab>
</x-tab>interpreterProxy pop: 2.</div>
<div><x-tab>
</x-tab>interpreterProxy pushInteger: (anInteger+myInteger).</div>
<div><br></div>
<div>Only slightly more sophisticated. Here, I also pull the
receiver and use the interpreterProxy to fetchInteger to get the
(0-indexed)<x-tab> </x-tab>first instance variable, pop
the stack and then push the sum.</div>
<div><br></div>
<div><br></div>
<div>--------- </div>
<div><br></div>
<div>STEP THREE: TEST THE PRIMITIVES TO SATISFY YOURSELF THEY
WORK.<x-tab> </x-tab></div>
<div><br></div>
<div><x-tab> </x-tab>Foo new
integerSeventeen 17</div>
<div><br></div>
<div><x-tab> </x-tab>Foo new
integerIdentity: 23 23</div>
<div><br></div>
<div><x-tab> </x-tab>Foo new
integerSum: 3 and: 4 7</div>
<div><br></div>
<div><x-tab> </x-tab>Foo new
myInteger: 3; integerSumWith: 4 7</div>
<div><br></div>
<div><br></div>
<div>--------- </div>
<div><br></div>
<div>STEP FOUR: TAKE A BREATH AND COMPILE THE CODE</div>
<div><br></div>
<div>This is so easy, its automagical! You only need to do two
things. First, add a single class method to FooPlugin, so that
the plugin knows the name of the module:</div>
<div><br></div>
<div><x-tab>
</x-tab>moduleName</div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>"return the name of this plug-in library"</div>
<div><br></div>
<div><x-tab>
</x-tab><x-tab>
</x-tab>^'Foo'</div>
<div><br></div>
<div><br></div>
<div>The rest is even easier, just execute the following:</div>
<div><br></div>
<div><x-tab>
</x-tab>FooPlugin translateDoInlining: true</div>
<div><br></div>
<div>and the code magically is produced in file 'Foo.c'</div>
<div><br></div>
<div><br></div>
<div>--------- </div>
<div><br></div>
<div>STEP FIVE: GO TO YOUR OPERATING SYSTEM AND BUILD AND INSTALL THE
MODULE.</div>
<div><br></div>
<div>To compile "Foo.c," you will also need some of the
interpreter support ".h" files, which you can obtain simply
by executing the following inside of Squeak:</div>
<div><br></div>
<div><x-tab>
</x-tab>InterpreterSupportCode writeMacSourceFiles</div>
<div><br></div>
<div>For me, I went to MPW and executed the following commands.
Your mileage may vary:</div>
<div><br></div>
<div>MrC "Macintosh HD:Desktop Folder:Squeaks:Squeak2.3
folder:Foo.c" -o Foo.c.x</div>
<div>PPCLink -o Foo "Foo.c.x" -t 'shlb' -c '????' -xm s
</div>
<div>"Macintosh HD:Desktop
Folder:MPW:Libraries:SharedLibraries:InterfaceLib" </div>
<div>"Macintosh HD:Desktop
Folder:MPW:Libraries:SharedLibraries:StdCLib" </div>
<div>"Macintosh HD:Desktop
Folder:MPW:Libraries:SharedLibraries:MathLib" </div>
<div>"Macintosh HD:Desktop
Folder:MPW:Libraries:PPCLibraries:StdCRuntime.o" </div>
<div>"Macintosh HD:Desktop
Folder:MPW:Libraries:PPCLibraries:PPCCRuntime.o" </div>
<div>"Macintosh HD:Desktop
Folder:MPW:Libraries:PPCLibraries:PPCToolLibs.o"</div>
<div><br></div>
<div>(You can use MPW's "Create Build Commands" feature to
build a makefile for you.)</div>
<div><br></div>
<div><br></div>
<div>The result of the compile is the generation of a Macintosh shared
library plugin file named "Foo." To install it, simply
copy the file into the same folder as your Squeak executable and
restart Squeak. The next time I ran the primitives (same
commands as before), they ran right as rain, but instead of running
the interpreter, they ran from the module. </div>
<div><br></div>
<div>[If you want to show that you have no faith, simply change the
calls to "FooPlugin doPrimitive:" with ^'Whew!'. To
really believe, start passing non-integer strings to the code and see
what happens.</div>
<div><br></div>
<div>After getting this working, I suggest readers then study the more
sophisticated code in the Squeak-Plugins category. I would
appreciate any comments about the preceding, and I will update after
incorporating all of the corrections.</div>
<div><br></div>
<div>Of course, all of the above is a profound example of the blind
leading the blind, but bootstrapping our way out of darkness a bit at
a time is the very heart of the Squeak philosophy, right?</div>
<div><br></div>
<div>Hope this helps.</div>
</body>
</html>