deep-c-rsc/JCGO/FAQ.txt

JCGO: Frequently Asked Questions
--------------------------------

Bellow are the most common questions about the JCGO software. The newcomers
should have a look into the "README" file first.


1. What is JCGO?
----------------

JCGO (pronounced as "j-c-go") is a software application which converts
(translates) programs written in Java into platform-independent C code, which
could, further, be compiled (by third-party tools) into highly-optimized
native code for the target platform and deployed.

JCGO is a powerful solution that enables your desktop, server-side and
embedded Java applications to take full advantage of the underlying hardware.
In addition, JCGO effectively protects your intellectual property by making
your programs, when compiled to native code, as hard to reverse engineer as if
they were written in C/C++.


2. Does JCGO fully support all classes including AWT, Swing and JDBC packages?
------------------------------------------------------------------------------

Yes, AWT/Swing and SQL/JDBC are fully supported by JCGO through Sun JDK/J2SE
v1.4.2 for Windows and Linux x86 (i.e., for translation and compilation an AWT
application you need JCGO-SUNAWT packages).


3. Is JCGO JDK6-compatible?
---------------------------

No, at present JCGO does not support features introduced in the 3rd Java
language specification (JLS 3). So, if your application really requires
JDK1.5+ functionality then look for some 3rd-party competing product like Java
to native code "through C" compilers or Direct Java to native code compilers.

4. Does JCGO support Linux?
---------------------------

Yes, the C code generated by JCGO could be compiled for Linux targets. More
over, Windows, Linux and SunOS Solaris on i586 (x86) and x86_64 (amd64) are
the most tested and supported target platforms at present.

5. Can I use JCGO to produce code for micro-controllers?
--------------------------------------------------------

JCGO is not really a MCU-specific tool by design but it could be used for such
purpose (typically with some additional porting efforts) as the compiled
program image size for simple applications could start from 8 KiB and most
immutable Java objects (like strings) go into read-only program sections. The
produced native code does not have any special requirements for the underlying
platform, does not contain any bytecode and does not require a Java VM. For
the memory recycling (if needed), JCGO runtime uses either Boehm GC (BDWGC) or
TinyGC.


6. Is performance good compared to a Java VM with JIT?
------------------------------------------------------

JCGO could be considered as a Java VM with ahead-of-time (AOT) compilation.
AOT has "pros" and "cons" compared to JIT.

The performance is nearly as good as if an the application was written in
C/C++ except for:
- "try {} catch/finally {}" construction is translated to a setjmp() (unlike
some other Java VM implementations where "try" is just a no-op if the block
completes normally);
- unlike a normal C/C++ application, memory is freed by a garbage collector
(so, for a real-time application, this might require significant efforts for
tuning it to make GC delays acceptable).


7. Can I use JCGO for embedded targets?
---------------------------------------

Yes, JCGO works, at least, for embedded Linux, Darwin and Windows
Mobile/PocketPC (WinCE) on arm, mips, sh and x86.

But the translation of a GUI application is a problem since you cannot use Sun
JDK for embedded targets, so, there exists only two ways - either use GNU
Classpath GTK peers (which is far from perfect compared to the Sun AWT
implementation but might, nonetheless, fit a particular application or Eclipse
SWT (which is supported for a dozen of targets and runs fine at least for GTK
and Win32 platforms (Mobile/PocketPC/WinCE is less well supported but the SWT
project is under active development at present). Also, there is the 3rd way -
to use some AWT-over-SWT implementation (like open-source "swingwt" or
proprietary "IBM J9 WEME ppro10 UI") but they are far from perfect (and not
under active development at this moment).

Anyway, typically, before compiling a Java application for an embedded
platform, it is good to compile it for the desktop running on similar OS
utilizing the same Java GUI toolkit. Then (if it works out-of-the-box on a PC)
recompile C files for the target embedded platform.


8. How can I run the JCGO translator on Linux/FreeBSD/SunOS?
------------------------------------------------------------

The JCGO translator executable binary is distributed as "jcgo.jar" file
suitable to be launched on any Java VM (e.g. Sun JRE v1.4 or higher).

Also note that the target platform does not depend anyhow on the platform
where the JCGO translator is launched.


9. I can't unpack some of the distributive .gz files with tar utility
----------------------------------------------------------------------

They are not corrupted. Try to use the recent tar utility version or use
the popular "7-Zip" archiver.


10. Is it possible to use JCGO to speed-up Android applications
---------------------------------------------------------------

No, at present this is impossible because JCGO does not support some of the
Java syntax defined in the JLS v3 (generics, enums, annotations, auto-boxing,
for-each loops).


11. Is the Tricore C compiler supported?
----------------------------------------

No, we haven't tried it yet. But it would probably work for you (with little
or even none modifications of the JCGO run-time files).


12. Should I use TinyGC or BoehmGC for my project?
--------------------------------------------------

It is recommend to use BoehmGC (BDWGC) unless the latter does not fit you (for
any purpose).


13. Is JCGO certified to be compatible with Sun Java?
-----------------------------------------------------

No, but JCGO is compatible (almost fully) with Sun J2RE v1.4. Use the official
JCK test suite to manually verify the compatibility. On the other hand, it is
possible to relax the strict compatibility with the Sun Java in favor of speed
(e.g., turn off array index checking).


14. Could I use JCGO with a commercial closed-source application?
-----------------------------------------------------------------

Sure. Everything (with the only exception) accompanying the JCGO could be used
in a commercial project. More over, most of the JCGO components are
open-source (mostly released under GPL plus the Classpath exception). The only
exception is: the Sun JDK 1.4 GUI/Sound/SQL back-ends (currently they are
available under the Sun Research-only license).


15. Is is possible to use JCGO for critical fault-tolerant Java applications?
-----------------------------------------------------------------------------

No, by the initial design, JCGO is for non-realtime and non-fault-tolerant
applications only.


16. Is JCGO reliable? Is it possible to formally prove its reliability?
-----------------------------------------------------------------------

We did our best to make JCGO as reliable as possible. But we can't formally
prove you its reliability. You can use the official JCK tests suite for this
purpose.


17. How can I use JCGO to compile a J2ME application for a WinMobile target?
----------------------------------------------------------------------------

J2ME is not officially supported. But you can use some library emulating J2ME
functionality on the top of a J2RE platform. Also, note that AWT is not
supported for WinCE targets (Windows CE, Windows Mobile, Pocket PC) but,
again, you can use some 3rd-party library emulating AWT over SWT.


18. The translator says "Cannot find class: java.lang.Object". What's wrong?
----------------------------------------------------------------------------

The problem is you haven't specified the source path for
"java/lang/Object.java". To solve the problem, specify "@$~/stdpaths.in"
string as the last command-line argument when launching the JCGO translator.


19. The translator says "File bad for class". What's wrong?
-----------------------------------------------------------

JCGO expects fully qualified class names to be specified. E.g.: if you want to
translate "myproject/src/pkg1/pkg2/MyAppMain.java" file then type
"jcgo -sourcepath myproject/src pkg1.pkg2.MyAppMain" or
"jcgo -sourcepath myproject/src pkg1/pkg2/MyAppMain.java". (Note that
"MyAppMain.java" should then reside in "myproject/src/pkg1/pkg2" rather than
in "myproject/src" folder directly.) "Hello" sample has no package, so it is
passed to JCGO translator as "Hello" or "Hello.java".


20. Is there a way to convert Java files without main()?
--------------------------------------------------------

Well, the purpose of JCGO is to translate Java applications to C code. Every
Java application starts with main() (even applets are started by some viewer
class like sun.applet.AppletViewer). So, at least, you should specify the
class name of your application containing main(). For the case when you
convert a library which is e.g. invoked through JNI, you can pass "Empty1"
class name (e.g., type "jcgo -sourcepath your_project_src;$~/examples/simple
Empty1 @$~/stdpaths.in YourClass1 YourClass2 ..."). Any additional classes
(specified in the command line) are not required to contain main().


21. How to convert multiple Java files in a directory with a single command?
----------------------------------------------------------------------------

Yes, there is a way to instruct JCGO to explicitly include some classes into
the translation set - just specify the class names (or the source file names,
or, even, you can use file wildcards) in the command line on JCGO invocation.
Alternatively, you can create some "your_response.in" file, put the class
names to it (on a one-per-line basis), and invoke JCGO specifying
"@your_project/your_response.in" at the command line's end. Note, however,
that JCGO discovers cross-class dependencies (including dynamic) so, possibly,
you won't need to explicitly specify many classes in the command line. (To see
whether a particular class is included in the compilation set, you can search
(among all .h files produced) for the qualified name of that class with dots
('.') replaced with underscores ('_'). Alternatively, Main.c file may contain
the list (named as "jcgo_classTable" of all classes included in the
compilation set but for the space considerations the list is omitted unless
Class.forName() is used.)


22. Is TurboC v2.0 supported by JCGO?
-------------------------------------

No, it is not officially supported by JCGO. While it is theoretically possible
to compile the generated code with TurboC compiler, it would be very hard in
the real world to produce the correct binary executable mostly because of the
limit imposed by that compiler for identifiers length (only the first 32
characters are significant instead of 128, at least, required by JCGO).


23. What are the 16-bit compilers supported?
--------------------------------------------

The list is shown in "Samples" file (see "For DOS 16-bit" section). The most
recommended ones are the recent versions of Digital Mars (DMC) and Open Watcom
(WatcomC) compilers.


24. How does JCGO work?
-----------------------

JCGO translates the whole Java application (including all the used Java
libraries) at once producing portable C code. That code (along with the code
in "include" folder and, possibly, in "native" folder) is compiled (either all
at once or on a file-by-file basis) to the target platform's object code
(which is then linked with the required libraries and deployed).


25. Could the translator itself run natively on Windows or Linux?
-----------------------------------------------------------------

Yes. It was written entirely in Java and could be translated by itself, and,
then, compiled for Win32 or Linux.


26. Is it possible to use JCGO legally for doing iPhone/iPad development?
-------------------------------------------------------------------------

Yes. JCGO produces C code compilable by Xcode GCC. JCGO offers full J2RE v1.4
compatible support on iPhone/iPad except for AWT/Swing/JDBC/JSound.


27. What are the use cases of JCGO_NOGC macro?
----------------------------------------------

JCGO_NOGC macro instructs the compiler to exclude the garbage collection
support from your application. There are several cases where you may succeed
without GC:
- the program terminates quickly (e.g. some utility just processes input data
and exists);
- the program does not allocate objects (or does allocate only limited number
of them - this is a so-called "object reuse" pattern);
- you define (and call there necessary) a JNI function that calls free() for a
given object.


28. Is there a sample command for using a particular C compiler with JCGO?
--------------------------------------------------------------------------

Look in "Samples" file (contained in the JCGO installation folder). E.g., the
section named as "solaris cc amd64" contains sample commands for compiling for
Solaris SunOS/X86 using SunC compiler for 64-bit code (the first sample turns
on the maximum J2SE compatibility but turns off most of the optimizations).


29. What are the use cases of "goclsp/clsp_asc" folder?
-------------------------------------------------------

If your application does not need I18N (internationalization), and does not
use new String(byte[]) and String.getBytes() (even indirectly) then it is
possible to exclude the I18N support (thus slimming down the executable size)
by passing "-sourcepath $~/goclsp/clsp_asc" argument (prior to
"@$~/stdpaths.in" one) to the translator.


30. Why does "Hello world" example contain so many classes translated?
----------------------------------------------------------------------

The C code translated for "Hello" sample class contains near 80 classes (and
near 280 methods) even without the I18N support because it uses NIO buffers,
system properties, thread stuff and lots of exceptions. If you are targeting
very limited environments then it might worth for you to write your own
println native method (instead of using System.out/err) which calls C puts().


31. Will the translated code size grow faster than that of the original code?
-----------------------------------------------------------------------------

Yes and no (depending on your application).

E.g., if your Java main() just do "System.out.println(new Date())" then the
translated C code would be quite large (~6 MiB) containing: Locales manager
(locale bundles), default locales, various date and decimal formatters,
timezone rules, full list of timezones, code obtaining current timezone (in a
portable way), various collections and hash maps (along with equals/hashCode()
methods of all used classes), a table of all constant strings for
String.intern() code, a list of all class names (because the Calendar uses
reflection API for its instantiation), properties parser (for locale files),
zip file deflater (to get locale property file from a compressed zip), full
system properties initializer code (gnu.classpath.VMSystemProperties), Java
"long" type support, etc.).

Here is the list of some dependencies:
- if HashMap/Set is used then JCGO translates all hashCode/equals() methods of
all translated classes and also puts them to class virtual table (the latter
exists for every class);
- if String.intern() is used then JCGO creates a table (in Main.c) all
constant strings in the translated application;
- if phantom/soft/weak leaks are used then JCGO includes weak link handling
module;
- if Class.forName() and/or reflection API is used then JCGO includes the
meta-information in C code (names of Classes, relevant method signatures,
etc.);
- if your code uses Exception class (or its subclasses) then the Java core
exceptions would be included too;
- if your native code uses JNI (pJniEnv parameter) then you need to include
JNI support (same for threads, floating point and "long" type support).

--- [ End of File ] ---