diff --git a/website/guide/compiling.html b/website/guide/compiling.html index 77718601..07b0cc14 100644 --- a/website/guide/compiling.html +++ b/website/guide/compiling.html @@ -46,6 +46,13 @@ account by the internal duk_features.h file, which resolves the final internal features based on feature requests, compiler features, and platform features.

+
+If you use Duktape feature options, you should define the feature options both +when compiling Duktape and when compiling any application code using the +duktape.h header. This is necessary because some feature options +affect the binary compatibility of the Duktape API. +
+

The available feature options can be found in duk_features.h. The table below summarizes the available options, in no particular order:

diff --git a/website/guide/portability.html b/website/guide/portability.html index a4a62f4a..67916a6d 100644 --- a/website/guide/portability.html +++ b/website/guide/portability.html @@ -228,16 +228,54 @@ V8, the following seem to work:

Dukweb is compiled using Emscripten, so you can also check out the Duktape git repository to see how Dukweb is compiled.

-

Using Duktape from a C++ program

+

Duktape and C++

-

To use Duktape from a C++ program, simply compile Duktape in plain C and use -duktape.h normally in your C++ program; duktape.h -contains the necessary glue to make this work. Specifically, it contains -extern "C" { ... } to avoid name mangling issues.

+

Duktape works with both C and C++ compilers and applications. You can +compile Duktape and the application with a C or a C++ compiler in any +combination. Even so, it is recommended to compile both Duktape and the +application with the same compiler (i.e. both with a C compiler or both +with a C++ compiler) and with the same compiler options.

-

Currently Duktape itself cannot be compiled in C++ mode. This is under -work but is not a trivial issue because many of the compiler defines and -headers are different (especially for pre C99/C++11).

+

The duktape.h header contains the necessary glue to make all +of these combinations work. Specifically, all symbols needed by Duktape +public API are inside a extern "C" { ... } wrapper (active only +if compiled with a C++ compiler). This ensures that such symbols are defined +and used without C++ name mangling. Specifically:

+ + + +

If you mix C and C++ compilation, you should do the final linking with the +C++ toolchain. At least when mixing gcc/g++ you may encounter something like:

+
+$ g++ -c -o duktape.o -Isrc/ src/duktape.c
+$ gcc -c -o duk_cmdline.o -Isrc/ examples/cmdline/duk_cmdline.c
+$ gcc -o duk duktape.o duk_cmdline.o -lm -lreadline -lncurses
+duktape.o:(.eh_frame+0x1ab): undefined reference to `__gxx_personality_v0'
+collect2: error: ld returned 1 exit status
+
+ +

One fix is to use g++ for linking:

+
+$ g++ -c -o duktape.o -Isrc/ src/duktape.c
+$ gcc -c -o duk_cmdline.o -Isrc/ examples/cmdline/duk_cmdline.c
+$ g++ -o duk duktape.o duk_cmdline.o -lm -lreadline -lncurses
+
+ +

Because duktape.h selects C/C++ data types needed by +Duktape and also does other feature detection, mixing C and C++ compilers +could theoretically cause the C and C++ compilers to end up with different +active features or data types. If that were to happen, Duktape and the +application would be binary incompatible (which would be difficult to +diagnose). This is usually not an issue, but to avoid the potential, compile +Duktape and the application with the same compiler.

Limitations