What is the relationship between `preparation`, `creation`, and `machine`?

[creationix]

I'm having a hard time understanding what these things are. There are docs for xsCreateMachine and the xsCreation that's used for it's setup. I see in the source to the tools there are some good default values for this configuration.

But I'm trying to link against the output of xsl and I can see in mc.xs.c there is the txPreparation* xsPreparation() function that returns a txPreparation struct that looks useful in customizing the xsCreation values.

What I don't understand is the role of these things and their relationship. My goal is to just use the mc.xs* files in my app, but I'm not sure how or why.

[creationix]

I have the following:

#include <stdio.h>

#include "xsAll.h"
#include "xs.h"

extern txPreparation *xsPreparation();

///////////////////////////////////////////////////////////////////////////////
// Main app testing design.
///////////////////////////////////////////////////////////////////////////////

int main(int argc, char *argv[])
{
    txPreparation *preparation = xsPreparation();

    xsCreation creation = {
        // What goes here?
    };

    // Create a new machine
    xsMachine *machine = xsCreateMachine(&creation, "myxs", NULL);
    if (!machine)
    {
        fprintf(stderr, "Problem creating machine\n");
        return -1;
    }

    // How do I bootstrap my code defined in `mc.xs.c` and `mc.xsi`?

    xsDeleteMachine(machine);
    return 0;
}

[creationix]

In the source to repl, I found the following:

	static txMachine root;
	int error = 0;
	txMachine* machine = &root;
	txPreparation* preparation = xsPreparation();

	c_memset(machine, 0, sizeof(txMachine));
	machine->preparation = preparation;
	machine->keyArray = preparation->keys;
	machine->keyCount = (txID)preparation->keyCount + (txID)preparation->creation.keyCount;
	machine->keyIndex = (txID)preparation->keyCount;
	machine->nameModulo = preparation->nameModulo;
	machine->nameTable = preparation->names;
	machine->symbolModulo = preparation->symbolModulo;
	machine->symbolTable = preparation->symbols;
	
	machine->stack = &preparation->stack[0];
	machine->stackBottom = &preparation->stack[0];
	machine->stackTop = &preparation->stack[preparation->stackCount];
	
	machine->firstHeap = &preparation->heap[0];
	machine->freeHeap = &preparation->heap[preparation->heapCount - 1];
	machine->aliasCount = (txID)preparation->aliasCount;

	machine = fxCloneMachine(&preparation->creation, machine, "tool", NULL);

But I'm not sure I need to clone a machine or what that means either.

[creationix]

Also, what does the -p flag in xsl mean? It seems to execute the JS at compile time. I'm guessing this is something like the snapshot feature in V8. In my learning app I have a shapes.js module with some native C functions and a main.js function that I can load using the same main() as in the repl example.

[phoddie]

Also, what does the -p flag in xsl mean?

The -p flag is preload, which runs the bodies of modules listed in the "preload" section of the manifest at build time. It is an error to invoke a host (native) function at preload time.

But I'm not sure I need to clone a machine or what that means either.

Cloning a machine creates a new virtual machine from a machine image (e.g. from a snapshot). That's what you want here.

You are on the right track, but you are attempting an integration we haven't prepared documentation for yet. I'm happy to take a look at the project to help move this along. Feel free to send me an email with the project files (peter at moddable dot com). I can probably code faster than explaining things via GitHub. ;)

[creationix]

Thanks for the help. You can close this if you want or leave it open so others can find it easier.

[phoddie]

Cool.