Thursday, November 19, 2009

Setting environment variables in Java

Have you ever noticed that the Java System class doesn't let you set environment variables? You can retrieve them using getenv() but there is no equivalent setenv() function.
First off, what is the environment? The manual entry for environ(7) describes the environment as:
an array of strings [that] have the form name=value. Common examples are USER (the name of the logged-in user), HOME (A user's login directory) and PATH (the sequence of directory prefixes that many programs use to search for a file known by an incomplete pathname).
It turns out that when you start up the JVM, it copies this environment into its own Map of Strings. The actual container it uses is an unmodifiable map, probably to be extra safe.
So in a running Java application we have 2 environments: the JVM copy that you can read via System.getenv() and the underlying environment that lives in the C library.
If we want to change the JVM's copy, we can do so using reflection. Or at least we should be able to, just as long as our code is not running in a sandbox. In that case you'd be right out of luck. Anyway, the code to fetch a modifiable copy of the environment could look like this:
import java.lang.reflect.Field; import java.util.Map; import java.util.HashMap; public class Environment { @SuppressWarnings("unchecked") public static Map<String, String> getenv() { try { Map<String, String> unomdifiable = System.getenv(); Class<?> cu = unomdifiable.getClass(); Field m = cu.getDeclaredField("m"); m.setAccessible(true); return (Map<String, String>)m.get(unomdifiable); } catch (Exception e) { } return new HashMap<String, String>(); } }
Calling System.getenv() returns us an UnmodifiableMap of Strings containing the copy of the C environment. In order to get to its squishy modifiable heart, we access the m member variable which is modifiable. This is because UnmodifiableMap uses the proxy pattern - it implements the Map interface, but delegates all calls for retrieving values off to a member variable Map that contains the values and does all the real work. The set methods throw UnsupportedOperation exceptions. By accessing that m we can change the JVM's copy of the environment from under its very nose. Heh heh.
Not so fast. On Windows this is slightly different. The environment there contains a different Map that allows you to search for variables in a case-insensitive way. System.getenv() returns one Map (the unmodifiable one, same as Linux) whereas System.getenv("value") looks up the value in the case-insensitive Map. In order to create a robust update-env implementation we should update both of these Maps. This needs some more reflection to get the Map in question out of the ProcessEnvironment, probably like this:
@SuppressWarnings("unchecked") public static Map<String, String> getwinenv() { try { Class<?> sc = Class.forName("java.lang.ProcessEnvironment"); Field caseinsensitive = sc.getDeclaredField("theCaseInsensitiveEnvironment"); caseinsensitive.setAccessible(true); return (Map<String, String>)caseinsensitive.get(null); } catch (Exception e) { } return new HashMap<String, String>(); }
An example of how this may be useful without going any further would be if you have the DISPLAY environment variable set but you cannot use it (for example you connect via ssh -X, start a background process, then disconnect closing the X session connection too). In this situation even if you tell java.awt to run headless it may see that DISPLAY is set, try to use it and throw an exception. By clearing DISPLAY we can use headless methods to create off-screen graphics, to send them to a printer or to save a fake screen shot to file maybe for automated testing.
However this is not enough to affect the environment for any child processes. They will still only see the original, unmodified environment that the JVM craftily made a copy of at start-up. The comment in java.lang.ProcessEnvironment says it all:
// We cache the C environment.  This means that subsequent calls
// to putenv/setenv from C will not be visible from Java code.
Grrrr! By far the easiest approach here is to just use the ProcessBuilder. This lets you change the environment before launching the child process. Win. End of post.
No! I really want to change the underlying C environment for no good reason!
In order to change that we have to resort to either JNI or JNA. Lets start with JNA, it is the easier of the two and needs less tools. Just download a jar file and with the Java Compiler you're good to hack.
In case you have not heard of it, JNA is to Java what ctypes is to Python - a byte-code library that lets you open native, compiled, shared libraries and call the C routines within directly from Java code. JNI on the other hand requires you to create C++ functions, compile these, then call them from Java.
Armed with the JNA classes we can wrap the standard setenv() and unsetenv() functions from the C library.
import com.sun.jna.Library; import com.sun.jna.Native; public class Environment { public interface LibC extends Library { public int setenv(String name, String value, int overwrite); public int unsetenv(String name); } static LibC libc = (LibC) Native.loadLibrary("c", LibC.class); }
That works fine on Linux, but on Windows we have to take a different approach. There neither setenv nor unsetenv exist, instead we have to call _putenv. This function accepts a "name=value" string, and if we pass "name=" we can delete a variable from the environment. Unfortunately this multi-platform approach messes up the code a fair amount. Here is one way to do it:
// Inside the Environment class... public interface WinLibC extends Library { public int _putenv(String name); } public interface LinuxLibC extends Library { public int setenv(String name, String value, int overwrite); public int unsetenv(String name); } static public class POSIX { static Object libc; static { if (System.getProperty("").equals("Linux")) { libc = Native.loadLibrary("c", LinuxLibC.class); } else { libc = Native.loadLibrary("msvcrt", WinLibC.class); } } public int setenv(String name, String value, int overwrite) { if (libc instanceof LinuxLibC) { return ((LinuxLibC)libc).setenv(name, value, overwrite); } else { return ((WinLibC)libc)._putenv(name + "=" + value); } } public int unsetenv(String name) { if (libc instanceof LinuxLibC) { return ((LinuxLibC)libc).unsetenv(name); } else { return ((WinLibC)libc)._putenv(name + "="); } } } static POSIX libc = new POSIX();
Here we use JNA to load either libc on Linux or the msvcrt DLL (which contains _putenv) on Windows. There are ugly casts in there, and other OSes are left as an exercise to the reader, but this means that I can call POSIX.setenv() or unsetenv() and have it work.
To complete the picture, the JNI equivalent of this would be:
public class Environment { public static class LibC { public native int setenv(String name, String value, int overwrite); public native int unsetenv(String name); LibC() { System.loadLibrary("Environment_LibC"); } } static LibC libc = new LibC(); }
The call to System.loadLibrary() loads a dynamic/shared library. On Linux it looks for "" and on Windows "Environment_LibC.dll". The implementation of those native calls could be like this C++ code:
#include "Environment_LibC.h" #include <stdlib.h> #ifdef WINDOWS #include <string> #endif struct JavaString { JavaString(JNIEnv *env, jstring val): m_env(env), m_val(val), m_ptr(env->GetStringUTFChars(val, 0)) {} ~JavaString() { m_env->ReleaseStringUTFChars(m_val, m_ptr); } operator const char*() const { return m_ptr; } JNIEnv *m_env; jstring &m_val; const char *m_ptr; }; JNIEXPORT jint JNICALL Java_Environment_00024LibC_setenv (JNIEnv *env, jobject obj, jstring name, jstring value, jint overwrite) { JavaString namep(env, name); JavaString valuep(env, value); #ifdef WINDOWS std::string s(namep); s += "="; s += valuep; int res = _putenv(s.c_str()); #else int res = setenv(namep, valuep, overwrite); #endif return res; } JNIEXPORT jint JNICALL Java_Environment_00024LibC_unsetenv (JNIEnv *env, jobject obj, jstring name) { JavaString namep(env, name); #ifdef WINDOWS std::string s(namep); s += "="; int res = _putenv(s.c_str()); #else int res = unsetenv(namep); #endif return res; }
You generate the header files using javah - that gives you the strange function names needed - and compile the code as C++ to produce a shared library:
javah Environment
g++ -shared -o -I$(JAVA_HOME)/include/linux -I$(JAVA_HOME)/include/
This library needs to be in one of the usual places to work - somewhere where it can be found by dlopen(). So either in /usr/lib, a directory where ldconfig looks, or in one of the paths in LD_LIBRARY_PATH. This depends on the OS you are using. For Windows, Solaris or Mac you need a whole different set of flags and incantations. You can see why I lean towards JNA, even though it has its own problems. For the record this is how to compile the JNI library on Windows using MinGW:
g++ -DWINDOWS -Wl,--kill-at -shared -o Environment_LibC.dll -I$(JAVA_HOME)/include/win32 -I$(JAVA_HOME)/include
That --kill-at switch is a real gotcha. Without it the function symbol that the MinGW compiler produces is not the one that the JVM was expecting. On Windows the library itself must be in the current directory, or in one of the directories listed in the PATH variable.
As you can see we repeat the whole setenv-and-unsetenv-do-not-exist dance and use _putenv() for both. Here I fudge it with a bit of ifdeffing. Meh.
Now that we have a way to call the C library's setenv() and unsetenv() (or equivalent), let's wrap it all up. Here are the final setenv() and unsetenv() functions that update the C environment and the Java one too:
// inside the Environment class... public static int unsetenv(String name) { Map<String, String> map = getenv(); map.remove(name); Map<String, String> env2 = getwinenv(); env2.remove(name); return libc.unsetenv(name); } public static int setenv(String name, String value, boolean overwrite) { if (name.lastIndexOf("=") != -1) { throw new IllegalArgumentException( "Environment variable cannot contain '='"); } Map<String, String> map = getenv(); boolean contains = map.containsKey(name); if (!contains || overwrite) { map.put(name, value); Map<String, String> env2 = getwinenv(); env2.put(name, value); } return libc.setenv(name, value, overwrite?1:0); }
Curiously enough ProcessEnvironment is wired so as to validate the values that you add to the "unmodifiable" Map, but the case insensitive equivalent on Windows is not validated. If you try and add an invalid environment variable, such as one with a name that contains =, only the unmodifiable map will throw an IllegalArgumentException. This makes it fairly robust as the nasty name doesn't trickle down to the underlying C environment, but for Windows we have to do an extra check manually.
I've uploaded a tarball with all the files mentioned on here together with the dependencies to my GBA Remakes site. So now you've no excuse to not go off setting environment variables like mad.
Of course you shouldn't really do any of this. This post was 60% "if you really need to", 40% "might be useful". ProcessBuilder is the way to go for changing the environment in child processes.
The only thing that you might want to do is change the environment in a running Java process, but even then it is probably easier to create a wrapper script or batch file that launches your program and fiddle the environment prior to launching the JVM. Using reflection to access all those inner member variables is pretty flaky - if they change their name in some future version, your code will stop working. Happy hacking :-)

Wednesday, November 11, 2009


If you have been reading the changes that I've been pushing out to Bunjalloo lately, you will have noticed that there are quite a few that are aimed at optimising parts of the code. There was a lot of low-hanging fruit in there and the rendering of some 200+ comment threads on reddit was starting to annoy me.

There's an old rule when it comes to optimising your code; don't. 2nd verse, same as the first. The 3rd rule of optimisation is to profile your code first. So that's what I did.

The good old way to see where the bottle necks are is to use gprof. You compile with profiling on by passing a couple of flags to gcc, run the program and it spits out a profile upon exit. You then run the gprof command line tool and that interprets the profile to give you a table of hot spots. From commit 5beaffd581ed it looked something like this:

Each sample counts as 0.01 seconds.
% cumulative self self total
time seconds seconds calls ms/call ms/call name
10.00 0.02 0.02 103228 0.00 0.00 Font::valueToIndex(unsigned int) const
10.00 0.04 0.02 68648 0.00 0.00 std::_List_iterator<HtmlElement*>::operator--()
7.50 0.06 0.01 701479 0.00 0.00 std::less<unsigned int>::operator()(unsigned int const&, unsigned int const&) const

Right there you can see that Font::valueToIndex was taking a lot of time, but I already knew that that method could be improved. The other C++ STL calls were trickier to track down. I use all sorts of STL containers, so the problem could have been anywhere...

A couple of years ago Google released their performance analysis tools. One of the advantages google-perftools' CPU profiler has over gprof is that the output shows function calls line-by-line in a nifty graphical representation. Running the profiler on the same code gave this output:

thumbnail of the analysis
Here is the original full-size image

From there, I could trace the call graph back from the "slow" STL call to my code see that the use of a std::set was causing problems. It was overkill anyway and a simple change improved things there.

The different output in the perftools analysis is probably due to the way it works compared to gprof. With gprof, you get a call to the profiling library added to each of your program's functions, which means you need to recompile all of your code. With the Google tools you don't need to recompile your code, you just have to link in the profiler library to your executable. It then hooks in to the start of the program and uses timers and signals to instrument the code, adding traces at the current point of execution. The result is that code that takes longer has more "hits", but the result is not exactly the same as gprof's output.

This is why being able to compile NDS code on the PC is a really good idea. These things are not impossible on the DS of course - counting the hblanks your slow function takes by changing the background color is a classic technique - but in general running unit tests, debugging, and doing performance analysis are much tougher to do on an embedded device.

Enough waffle. All this means that the next version of Bunjalloo may be a bit nippier, hopefully.

Friday, November 06, 2009

NDS thumbnail preview in Nautilus

When you insert a cartridge into a Nintendo DS, the start menu shows a little image or logo of the game. Homebrew games for the DS can also add their own logos and these show up when you view them in Moonshell or whatever menu your cartridge happens to use.

Ages ago I wrote a little script to show these images as the preview icon for NDS files in the Gnome file browser Nautilus. The script is about a hundred lines of Python and it's available here.

The setup file in that download tarball associates the icon-extracting command to the MIME-type of the Nintendo DS file. If you use an older distro then you may have to associate the script with the generic application/octet-stream MIME type. The script filters by file name anyway. This association is not done using the usual Nautilus scripting method, where you add a script to ~/.gnome2/nautilus-scripts/, but rather using gconf variables.

If you need to uninstall the icon preview for some reason, you can run:

gconftool-2 -u /desktop/gnome/thumbnailers/application@x-nintendo-ds-rom

Oh, and while we're here I recommend you go and play the absolutely brilliant nostalgia-fest that is Manic Miner in the Lost Levels.