3DICC / SqueakNim

Commit 24d7cba16fe8be4c961b839a4dcf33456ec052d2

Authored by Göran Krampe
1 parent 70473583

Fixing README

Inline Side-by-side
Showing 1 changed file with 45 additions and 51 deletions
README.md
  View file @24d7cba
... ... @@ -28,7 +28,7 @@ How do I use it?
28 28 Example:
29 29  
30 30 ```
31   - system: aString
  31 +system: aString
32 32 "Some kind of comment"
33 33  
34 34 <apicall: long 'system' (char*) module: 'libSystem.dylib'>
... ... @@ -42,31 +42,29 @@ Then comes the so called pragma that describes the C function to call:
42 42 ```
43 43 <apicall: long 'system' (char*) module: 'libSystem.dylib'>
44 44 ```
45   -Function specification:
46   - - should be the first line in the method
47   - - enclosed in angle brackets: < > containing:
48   - 1. Calling Convention, either apicall: (Pascal convention) or cdecl: (C convention)
49   - - Mac - use either one
50   - - Unix - use cdecl
51   - - Windows - use apical
52   - 2. Return Type (see types)
53   - 3. External Function Name (literal string)
54   - 4. Argument Types (a literal array)
55   - 5. Module - "module: " + [filename of the external library (literal string)] (see below).
  45 +Function specification should be the first line in the method and enclosed in angle brackets: < > containing:
  46 +1. Calling Convention, either apicall: (Pascal convention) or cdecl: (C convention)
  47 + - Mac - use either one
  48 + - Unix - use cdecl
  49 + - Windows - use apical
  50 +2. Return Type (see types)
  51 +3. External Function Name (literal string)
  52 +4. Argument Types (a literal array)
  53 +5. Module - "module: " + [filename of the external library (literal string)] (see below).
56 54  
57 55 ```
58 56 ^self externalCallFailed.
59 57 ```
60 58  
61   -Failure handler
62   - - normal smalltalk code
63   - - executed if the linking to or calling the external function fails
64   - - API calls don't know how to communicate failure like Squeak primitives do, so:
65   - - it does not tell you whether the external function succeeded
66   - - the most common code is simply '^self externalCallFailed.'
  59 +Failure handler:
67 60  
68   -Argument Types
69   - - must be names of ExternalTypes, either:
  61 +* normal smalltalk code
  62 +* executed if the linking to or calling the external function fails
  63 +* API calls don't know how to communicate failure like Squeak primitives do, so:
  64 + * it does not tell you whether the external function succeeded
  65 + * the most common code is simply '^self externalCallFailed.'
  66 +
  67 +Argument Types must be names of ExternalTypes, either:
70 68 - atomic types (see ExternalType class>>initializeFFIConstants and ExternalType class>>initializeAtomicTypes):
71 69 void
72 70 bool
... ... @@ -84,19 +82,17 @@ Argument Types
84 82 double (double-precision float)
85 83  
86 84 Structure Types [4]
87   - - subclass of ExternalStructure
88   - - class>>fields that returns an array of field descriptions (see below)
89   - - Example:
90   - fields
91   - ^#((red 'byte')(green 'byte')(blue 'byte'))
92   - - class>>initialize which includes "self defineFields" (which must be
93   -called before using the class)
94   - - refer to as MyExternalStructure* (to indicate that the argument or return is a pointer to that structure)
  85 +* subclass of ExternalStructure
  86 +* class>>fields that returns an array of field descriptions (see below), example:
  87 + fields
  88 + ^#((red 'byte')(green 'byte')(blue 'byte'))
  89 +* class>>initialize which includes "self defineFields" (which must be called before using the class)
  90 +* refer to as MyExternalStructure* (to indicate that the argument or return is a pointer to that structure)
95 91  
96 92 Field description [4]
97   - - 2-element array (or three but that does something else, I'm not sure what):
98   - - first element is the field name
99   - - second is the type
  93 +* 2-element array (or three but that does something else, I'm not sure what):
  94 + * first element is the field name
  95 + * second is the type
100 96  
101 97 Module Name
102 98 - depends on the platform
... ... @@ -108,29 +104,27 @@ Module Name
108 104 - For Classic applications, use 'InterfaceLib'
109 105 - For Carbon libs, use 'CarbonLib'
110 106  
111   -Module Location - where the external library file lives
112   - - depends on the platform
113   - - Mac
114   - - pre Snow Leopard
115   - - checks VM path and common library paths
116   - - Snow Leopard
117   - - only looks in VM bundle's Resources file, you must either [5]:
118   - - store all external libraries there
119   - - ln -s path/to/library path/to/VM/Resources/library_name
120   - - Change the VM's Info.plist "SqueakPluginsBuiltInOrLocalOnly" key from "true" to "false."
  107 +Module Location, where the external library file lives
  108 +- depends on the platform
  109 + - Mac
  110 + - pre Snow Leopard
  111 + - checks VM path and common library paths
  112 + - Snow Leopard
  113 + - only looks in VM bundle's Resources file, you must either [5]:
  114 + - store all external libraries there
  115 + - ln -s path/to/library path/to/VM/Resources/library_name
  116 + - Change the VM's Info.plist "SqueakPluginsBuiltInOrLocalOnly" key from "true" to "false."
121 117 Caveats
122   - - security
123   - - malicious users could call arbitrary functions in the OS e.g. "format c:" from "system.dll" [7]
124   - - VMs do not protect against buffer overflow from bad parameters [8]:
125   - "this would require an attacker to execute arbitrary Smalltalk
126   - code on your server. Of course if they can do that they own you
127   - anyway, especially if you allow FFi or use the OSProcess plugin" - John McIntosh
  118 +- security
  119 + - malicious users could call arbitrary functions in the OS e.g. "format c:" from "system.dll" [7]
  120 + - VMs do not protect against buffer overflow from bad parameters [8]:
  121 + "this would require an attacker to execute arbitrary Smalltalk
  122 + code on your server. Of course if they can do that they own you
  123 + anyway, especially if you allow FFi or use the OSProcess plugin" - John McIntosh
128 124  
129 125 * difficulty
130   - - if you make a mistake you'll not drop into the debugger but Squeak will
131   -just crash [2]
132   - - If you crash Squeak when it is running the garbage collector, then you
133   -know your FFI code is leaking bits into object memory [2]
  126 + - if you make a mistake you'll not drop into the debugger but Squeak will just crash [2]
  127 + - If you crash Squeak when it is running the garbage collector, then you know your FFI code is leaking bits into object memory [2]
134 128  
135 129 What do I need to use FFI with Squeak?
136 130  
... ...