ls2module SDK version 1 (update 2014-05-30)

Using the LavishScript 2.0 Module SDK (ls2module) to interface with a LavishScript 2.0 environment from C++

ls2module SDK version 1 (update 2014-05-30)

Postby WhiteSlax » Sat Sep 08, 2012 9:40 pm

Updated link 2014-05-30: http://www.lavishsoft.com/downloads/Lavish.LS2Module.sdk1.20140529.1.exe - includes ls2il.exe Build 0.10.20140529.1, and has an optional -verbose switch that provides additional debug tracing during the execution.

Below is mostly the unedited original post

Without further ado here is version 1 of the SDK. This is the first public alpha, or beta, or whatever you want to call it that happens to mean there's more to be done before it's official, of the SDK.

The SDK does include ls2il.exe which was first distributed in another thread here on the forums. For now I'll stick to just releasing the SDK, no standalone ls2il.exe. ls2il.exe is found in the bin folder of the SDK install.

It also includes a sample Module, LS2M-Foo, with a Visual Studio 2010 project to build it. LS2M-Foo is fairly well commented...

The SDK does not currently include this sample ls2il code that demonstrates loading LS2M-Foo, calling the "New" static method of LS2 type "Foo.Foo", to create an ActualFoo C++ object, to print its value and the name of its type.
Code: Select all
; LavishScript 2.0
; IL -> LS2VM bytecode test


function
.meta "Name" "Main"
.registers 4
; we need to register and load the Foo module LS2M-Foo.dll
RESOLVETYPE      0, "LS2.Module"
RESOLVESTATICMETHOD   1, register[0], "Register"
REREFERENCE      2, null
DUPLICATE      3, {null, "LS2M-Foo", "LS2M-Foo.dll" }
ARRAYSET      register[3], 0, register[2]
CALLSTATICMETHOD   register[1], register[3]
DEREFERENCE      2, register[2]
RESOLVEMETHOD      1, register[0], "Start"
FASTCALLMETHOD      register[1], register[2]

; now call function[1]
FASTCALL function[1]
endfunction

function
.meta "Name" "UseFoo"
.registers 2
RESOLVETYPE      0, "Foo.Foo"
RESOLVESTATICMETHOD   0, register[0], "New"
REREFERENCE      1, null
FASTCALLSTATICMETHOD   register[0], register[1], "Initial value"
DEREFERENCE      1, register[1]
FASTCALL       function[2], register[1]
FASTCALL       function[3], register[1]
endfunction

; print
function
.meta "Name" "Print"
.registers 1

; Note: It is possible to pre-cache type/method/property/etc lookups into chunk-level values instead of doing it on demand

RESOLVETYPE       0, "System.Console"
RESOLVESTATICMETHOD       0, register[0], "Print"
FASTCALLSTATICMETHOD    register[0], input[0]
endfunction

; print type of
function
.meta "Name" "PrintTypeof"
.registers 2
RESOLVETYPE       0, "System.Console"
RESOLVESTATICMETHOD       0, register[0], "Print"
TYPEOF         1, input[0]
FASTCALLSTATICMETHOD    register[0], register[1]
endfunction


There have been some minor changes to the IL that I will be updating existing posts for tomorrow.
Notably,
* meta tags storing arbitrary values can be added to the chunk and to functions
* New operand keywords "exception", "function", "function[#]"
* CALL and FASTCALL also now require a Function as opposed to a register number

This *is* sufficient to build an arbitrary new LS 2.0 type, and test it in the IL. As demonstrated by the sample Module and the above IL script. :) And when the scripting language is implemented, or another arbitrary language is compiled to LS2 IL, it will still work, because it's still the same IL and VM underneath. In other words, you will be able to start forward conversions to LavishScript 2.0 immediately with this release, however bear in mind that some parts of the API might have to change yet. It is looking pretty impressive, especially in comparison to LS1. ;)

I do expect a question about how this will integrate with ISXDK. I will get back to you on that, but I do NOT intend to increment the ISXDK version number OR combine the SDK at this time (as the LS1 SDK is). However, you will be able to access the LS 2.0 environment from an IS extension with a minor update to the ISXDK (this update is not yet implemented), in combination with the ls2module SDK.

I have a lot of information you'll want, but for now you might just have to try playing with the SDK because I also need to eat and sleep. ;)

-- changes
** newer change sets are found in replies to this thread **

sdk 1 - Environment version 0.6.20121006.1
* IL changes:
- implemented SWITCH instruction, which operates on either an Array with an integer 2nd opnd, or Table with a string

sdk 1 - Environment version 0.6.20121005.1
* sdk changes:
- ILS2CodeBoxFunction now has an ExecuteAtomic method
- ILS2CodeBoxMethod, StaticMethod, Property, StaticProperty can now be backed by an ILS2CodeBoxFunction, and all have required GetILS2CodeBoxFunction methods. Methods and StaticMethods backed by functions MAY execute non-atomically if used in a non-atomic context
* LS2 environment changes
- Exception moved to System.Exception
- chunk metadata is now interpreted for type declarations. TODO: they are not yet automatically removed when the chunk is destroyed

sdk 1 - Environment version 0.6.20121004.2
* LS2 environment changes
- when Function bytecode fails to read, the correct exception is now thrown (it was previously getting overwritten by the wrong exception)
- fixed a bug with reading empty arrays from bytecode

sdk 1 - Environment version 0.6.20121004.1
* sdk changes
- LS2StandardEnvironment::UnregisterScript should now work properly
- UnregisterModule, UnregisterScript and UnregisterType now properly give an exception upon failure
* LS2 environment changes
- System.Exception base type now exists
- implemented Modulo and Power operations for decimal and integer value types
* IL changes
- Exception handling instructions are now TRY, LEAVE, ENDFINALLY and no longer include GETEXCEPTIONHANDLER or SETEXCEPTIONHANDLER
- added 'this' operand keyword
- REREFERENCE instruction can now accept a VT_Reference as destination, to update an existing reference
- math instructions now require a destination (lvalue) operand, meaning lvalue=left <op> right instead of lvalue=lvalue<op>right
- fixed a bug with Tables not accepting String values

sdk 1 - Environment version 0.5.20120920.1
* sdk changes
- bytecode reading errors now always produce exceptions
- ls2il.exe updated to load and execute a LS2.Script
- ls2il.exe: additional parameters are passed in to the main function as a string array
- event objects are now reference counted
- UnregisterType has a ppException, updated LS2Type_Foo to match
- new bool operator !() on SmartRef, allows e.g. "if (!pValue)"
- added NewScript, NewEvent, NewThread, NewModule
* LS2 environment changes
- implemented LS2.Script, LS2.Thread
- added missing LS2.Module.Filename property
- Scripts and Modules can no longer be Unregistered until they are Stopped
- Added Table and Event types (though incomplete)
- implemented Threads and LS2.Thread type
* IL changes
- new instructions LESS, LESSEQUAL, EQUAL, LNOTEQUAL, LGREATER, LGREATEREQUAL, JZ, JNZ
- 'registers' and 'inputs' added as operand keywords

sdk 1 - Environment version 0.3.20120909.1
* sdk changes
- ILS2Module::Initialize now includes an ILS2Array *pInputs
- ILS2Module::Shutdown is now asynchronous whenever possible. If provided an ILS2Signal interface, shutdown may by delayed indefinitely.
- ILS2AvailableModule::Start now includes an ILS2Array *pInputs, which translates directly to ILS2Module::Initialize
* LS2 environment changes
- LS2.Module.Start() now accepts any number of inputs, which translates directly to ILS2Module::Initialize
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 :)

Postby Amadeus » Sun Sep 09, 2012 3:27 am

I do expect a question about how this will integrate with ISXDK. I will get back to you on that, but I do NOT intend to increment the ISXDK version number OR combine the SDK at this time (as the LS1 SDK is). However, you will be able to access the LS 2.0 environment from an IS extension with a minor update to the ISXDK (this update is not yet implemented), in combination with the ls2module SDK.


This is the part I'll be waiting for with bated breath.
Amadeus
 
Posts: 7
Joined: Sun Sep 09, 2012 3:26 am

Re: ls2module SDK version 1 :)

Postby WhiteSlax » Sun Sep 09, 2012 3:37 pm

Inner Space build 5671 adds the current build of the LS2 Environment to Inner Space and the ISXDK (32a), so you can start getting a feel for that. This build of IS does NOT yet expose any IS functionality into LS2, the sole purpose of this build is to provide the API. The script portion of the environment interface is also not yet implemented; that'll also be coming soon. Again, the purpose of this build is to provide the API. ;)

From the ISXDK 32a changelog:
Version 32a
- LavishScript 2.0 support now built into ISInterface:
* bool GetLavishScript2Environment(unsigned int LS2MODULE_SDK_VERSION, void **ppEnvironment)
* To use the LS2 Environment, you will need the ls2module development kit!
* Call the static ILS2Module::AttachEnvironment before instantiating any LS2 objects
* Specifically embedding one or more LS2 Modules into your IS extension is optional; Types can be
implemented by your IS extension by accessing the Environment. However, it is possible to
register any number of Modules by providing loaders, as opposed to only loading DLL files.


It is safe to call this function with ISXDK 32a and any build of IS 1.11; it will return false on a build older than 5671.

So.. you could do something like...
Code: Select all
// have LS2 environment interfaces..
#include <ls2module.h>
#pragma comment(lib,"ls2module.lib")

bool MyISX::Initialize(ISInterface *p_ISInterface)
{
   pISInterface=p_ISInterface;

   // LS2MODULE_API_VERSION is a #define with this sort of purpose
   LavishScript2::ILS2StandardEnvironment *pEnvironment = 0;
   pISInterface->GetLavishScript2Environment(LS2MODULE_API_VERSION,(void**)&pEnvironment);
   if (pEnvironment)
   {
      ILS2Module::AttachEnvironment(pEnvironment); // this is important! :)
      InitLavishScript2Stuff(pEnvironment);

   }

   return true;
}

extern unsigned char[] someEmbeddedScript;

void MyISX::InitLavishScript2Stuff(LavishScript2::ILS2StandardEnvironment *pEnvironment)
{
   // Register MyISX.FOO as a type!
   LavishScript2::LS2SmartRef<LavishScript2::ILS2CodeBoxType> pMyFooType;
   pEnvironment->RegisterType("MyISX.Foo", 0, pMyFooType);
   pMyFooType->RegisterStaticMethod(...); // etc.

   // Register some Module we decided to embed!
   pEnvironment->RegisterModule("MyModule",myModuleLoader);
   // we can even load it ourselves if we want.. ...

   // Register some Script we decided to embed!
   LavishScript2::LS2SmartRef<LavishScript2::LS2Buffer> pBuffer;
   // initilize pBuffer, keep ref count at 1 from our point of view so if the script doesn't keep it, smartref Deletes it
   pBuffer.Set(*new LavishScript2::LS2Buffer(someEmbeddedScript,sizeof(someEmbeddedScript)),false);
   pEnvironment->RegisterScript("MyScript",pBuffer);
}
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 :)

Postby WhiteSlax » Thu Sep 20, 2012 8:30 pm

Bumping thread for the 0.5.0920.1 release, original post updated with changelog
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 :)

Postby WhiteSlax » Thu Oct 04, 2012 3:02 pm

Updated 2012-10-04
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 :)

Postby WhiteSlax » Sat Oct 13, 2012 3:42 pm

sdk 1 - Environment version 0.6.20121013.1
* IL changes:
- implemented instruction NEWOBJECT lvalue, constructor, args
- NEWARRAY instruction now allows a 3rd operand indicating the Type to use for allocation
- added field[#] operand type, to get a field value from the 'this' object
- added GETFIELD and SETFIELD instructions

* SDK changes:
- new interface ILS2CodeBoxValueAllocator can be registered on a type to provide NEWOBJECT support
- method and property interfaces now have a GetParentType method
- added LS2ManagedObject, ILS2CodeBoxManagedObject, LS2CodeBoxValue_LS2ManagedObject
- Types now have a static field list
- ILS2Array resize methods now include an optional type parameter for allocation, and may propagate an exception
- ILS2CodeBoxType now has field registration functions

* environment changes:
- added WriteLine{string} alias for System.Console.WriteLine
- Array type is now System.Array and includes an allocator
- System.Int32 includes an allocator
- String is now System.String and includes an allocator
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 (update 2012-10-17)

Postby WhiteSlax » Wed Oct 17, 2012 2:34 pm

sdk 1 - Environment version 0.6.20121017.1
* SDK changes:
- fixed some #defines that were missing explicit LavishScript2 namespace usage
- ToString now follows LS2's standard return value pattern (sets a Reference)

* environment changes:
- LS2 hosts (e.g. ls2il.exe, Inner Space) are now notified of unhandled LS2 exceptions
- CALLMETHOD instruction no longer produces an errant "Unhandled instruction" exception
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 (update 2012-10-21)

Postby WhiteSlax » Sun Oct 21, 2012 2:24 pm

sdk 1 - Environment version 0.7.20121021.1
* environment changes
- Integer and Decimal types are now split into 8-64 bit signed and unsigned variants where appropriate
- added Boolean type
- added FQN aliases for methods to link with new ls2csc builds
- all standard types are now under namespaces, e.g. LavishScript2, System, etc

* SDK changes:
- LS2CodeBoxValue::GetType no longer requires the environment passed in
- added NewBoolean to the environment interface
- NewInteger and NewDecimal now take a value type parameter
- Updated object view macros for integer and decimal type variants, and the new Boolean type

* IL changes:
- u# is now a recognized value prefix, where i8 i16 i32 i64 are signed variants, and u8 u16 u32 u64 are unsigned variants

The latest ls2csc build from github is included in this SDK, including patches submitted by Noob536 and Vendan
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 (update 2012-10-22)

Postby WhiteSlax » Mon Oct 22, 2012 8:44 pm

sdk 1 - Environment version 0.7.20121022.1
* IL changes
- new instructions IS and AS

* SDK changes
- Types now have interface-related methods... Register, Unregister, Enumerate...
- added ILS2Enumerator class and LS2CodeBoxValue_Enumerator

* environment changes
- implemented System.Array's IEnumerable interface

with this update, ls2csc supports foreach(x in IEnumerable) and using(IDisposable) statements :)
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Re: ls2module SDK version 1 (update 2012-10-26)

Postby WhiteSlax » Fri Oct 26, 2012 8:19 am

This release re-implements Field as an interface (okay an abstract class like the lot of them, but play along), similar to Property. This also means new instructions to support the new capabilities. And, importantly, that System.Enum could be supported. ;)

sdk 1 - Environment version 0.8.20121026.1
* IL changes
- GETFIELD and SETFIELD now accept Field instead of numbers, and operand order is the same as GETPROPERTY/SETPROPERTY
- new instructions RESOLVEFIELD, RESOLVESTATICFIELD, GETSTATICFIELD, SETSTATICFIELD
- bytecode now handles interfaces, base types

* SDK changes
- all new Field implementation in ILS2CodeBoxType. static fields are by name, non-static fields are by numeric index
- value types VT_Enum, VT_Field, VT_StaticField
- exceptions can now be "Tagged" with strings as they propagate (e.g. with stack information). could just as easily be changed to be taggable with arbitrary values instead of just strings...
- added templated GetAt for ILS2Array and ILS2Table to simplify conversions
- new interfaces ILS2CodeBoxField and ILS2CodeBoxStaticField

* environment changes
- initial implementation of System.Enum type
- Reference objects support a metatable...

ls2csc is also updated to the latest version from github (up to this commit), including new multi-file input patches from Vendan.
WhiteSlax
Site Admin
 
Posts: 97
Joined: Mon May 07, 2012 7:24 pm

Next

Return to LS2 Module Development

Who is online

Users browsing this forum: No registered users and 1 guest

cron