ABI stability for duk_eval_raw and duk_compile_raw

[HouQiming]

Duktape 2.1 broke the binary compatibility of duktape.c as a few DUK_COMPILE_foo values have changed. This could cause complications when updating our production system, where a bunch of static libraries are written in different languages and managed by different teams. DUK_COMPILE_SHEBANG seems to be the culprit.

I would really appreciate if duktape could:

• Provide a non-macro public interface like duk_eval_raw / duk_compile_raw to simplify non-C language bindings
• Make DUK_COMPILE_SAFE / DUK_COMPILE_NOSOURCE public since they're pretty useful when writing language bindings
• Ideally, even the internal flags should have stable values since they are used in macros like duk_peval and changing them breaks binary compatibility

TL;DR Instead of the cleaner-looking:

#define DUK_COMPILE_EVAL                  (1 << 3)    /* compile eval code (instead of global code) */
#define DUK_COMPILE_FUNCTION              (1 << 4)    /* compile function code (instead of global code) */
#define DUK_COMPILE_STRICT                (1 << 5)    /* use strict (outer) context for global, eval, or function code */
#define DUK_COMPILE_SHEBANG               (1 << 6)    /* allow shebang ('#! ...') comment on first line of source */
#define DUK_COMPILE_SAFE                  (1 << 7)    /* (internal) catch compilation errors */
#define DUK_COMPILE_NORESULT              (1 << 8)    /* (internal) omit eval result */
#define DUK_COMPILE_NOSOURCE              (1 << 9)    /* (internal) no source string on stack */
#define DUK_COMPILE_STRLEN                (1 << 10)   /* (internal) take strlen() of src_buffer (avoids double evaluation in macro) */
#define DUK_COMPILE_NOFILENAME            (1 << 11)   /* (internal) no filename on stack */
#define DUK_COMPILE_FUNCEXPR              (1 << 12)   /* (internal) source is a function expression (used for Function constructor) */

I'd prefer the messy-but-compatible:

#define DUK_COMPILE_EVAL                  (1 << 3)    /* compile eval code (instead of global code) */
#define DUK_COMPILE_FUNCTION              (1 << 4)    /* compile function code (instead of global code) */
#define DUK_COMPILE_STRICT                (1 << 5)    /* use strict (outer) context for global, eval, or function code */
#define DUK_COMPILE_SHEBANG               (1 << 12)    /* allow shebang ('#! ...') comment on first line of source */
#define DUK_COMPILE_SAFE                  (1 << 6)    /* (internal) catch compilation errors */
#define DUK_COMPILE_NORESULT              (1 << 7)    /* (internal) omit eval result */
#define DUK_COMPILE_NOSOURCE              (1 << 8)    /* (internal) no source string on stack */
#define DUK_COMPILE_STRLEN                (1 << 9)   /* (internal) take strlen() of src_buffer (avoids double evaluation in macro) */
#define DUK_COMPILE_NOFILENAME            (1 << 10)   /* (internal) no filename on stack */
#define DUK_COMPILE_FUNCEXPR              (1 << 11)   /* (internal) source is a function expression (used for Function constructor) */

[svaarala]

Unfortunately the cost of guaranteeing binary compatibility between minor releases (not just patch releases) is quite high in practice. It prevents many reworks (which may affect the internal helper functions which are used by API macros), it prevents keeping flags and constants clean (as you note above), and it also prevents changing the bytecode which would break dump/load.

While I understand your pain, this seems overall too much of a cost to me -- especially because major versions would need to break binary compatibility from time to time anyway, and you'd be faced with the same problem anyway.

[HouQiming]

After re-reading the newest API documentation, I found that my use case is already covered by duk_pcompile_lstring_filename and I don't have to call the raw functions any more.

Since general binary compatibility is too costly, can you make a function equivalent to the duk_pcompile_lstring_filename macro to at least simplify language bindings a bit? It seems to be the most general variant among all those compile/eval macros.

Also, it could be useful if that interface could be somehow endorsed in the guide / changelog. Currently it's not immediate clear which macro is most useful for people writing bindings / wrappers.

Thanks.