Embedder-HOWTO added

1 files changed, 104 insertions, 0 deletions

diff --git a/doc/Embedder-HOWTO.txt b/doc/Embedder-HOWTO.txt
new file mode 100644
index 0000000..ac2e2ec
--- /dev/null
+++ b/doc/Embedder-HOWTO.txt
@@ -0,0 +1,104 @@
+Embedder HOWTO
+--------------
+
+This document explains how to embed Jim into an existing application, in
+order to make the application scriptable, to write parts of the application
+in Jim on top of a C core, or just to use Jim as a configuration file format.
+
+STEP 1
+------
+
+Copy jim.c and jim.h into your project, and modify the Makefile in
+order to compile jim.c and link jim.o into your application.
+
+STEP 2
+------
+
+Include the file "jim.h" in your application, in the file where you
+defined your main() function. Before to include jim.h, only for this
+file you have to define JIM_EMBEDDED. So the two lines to add are:
+
+  #define JIM_EMBEDDED
+  #include "jim.h"
+
+Then add the call to Jim_InitEmbedded(); into your main() function.
+This call need to be placed before any other call to the Jim API.
+Example:
+
+  int main(int argc, char **argv) {
+     ....
+     Jim_InitEmbedded();
+     ...
+
+     /* Here is possible to call other Jim API functions */
+  }
+
+NOTE: If you require to call the Jim API from other files of your project
+you have just to include "jim.h" WITHOUT to define JIM_EMBEDDED.
+This definition is only useful inside the file that calls Jim_InitEmbedded(),
+i.e. in the file containing your main() function.
+
+STEP 3
+------
+
+Use the Jim API in order to glue your program with Jim. First of all you
+probably want to create an interpreter, add some command, and use
+Jim_Eval() to execute Jim scripts from your application:
+
+  #define JIM_EMBEDDED
+  #include "jim.h"
+  
+  #include <stdio.h>
+  
+  static int foobarJimHelloCommand(Jim_Interp *interp, int argc,
+          Jim_Obj *const *argv)
+  {
+      printf("Hello World!\n");
+      return JIM_OK;
+  }
+  
+  int main(void)
+  {
+      Jim_Interp *interp;
+      
+      Jim_InitEmbedded();
+      printf("Welcome to The FooBar Application\n");
+  
+      /* Create an interpreter */
+      interp = Jim_CreateInterp();
+      /* Add all the Jim core commands */
+      Jim_RegisterCoreCommands(interp);
+      /* Add a new foobar.hello command to Jim */
+      Jim_CreateCommand(interp, "foobar.hello", foobarJimHelloCommand, NULL);
+      /* Eval some Jim code. */
+      Jim_Eval(interp, "for {set i 0} {$i < 10} {incr i} {foobar.hello}");
+      return 0;
+  }
+
+STEP 4
+------
+
+To test this example complile with:
+
+  gcc main.c jim.c -ldl
+
+(you need to link against the 'dl' lib because Jim supports dynamic loading
+ of extensions)
+
+The run the example with ./a.out. The output should be:
+
+  Welcome to The FooBar Application
+  Hello World!
+  Hello World!
+  Hello World!
+  Hello World!
+  Hello World!
+  Hello World!
+  Hello World!
+  Hello World!
+  Hello World!
+  Hello World!
+
+Check the API reference for more information.
+
+