Building ZXing for Android – lessons learned

Updated based on feedback from the ZXing team.

Tonight I decided to try my hand again at building an Android app – this time, one that should in theory be easy and yet feature-rich enough to learn from.  It was far from the simple experiment it ought to have been, so I’m sharing my experience to hopefully save you the reader some time if you try this yourself!

ZXing is the heart of the Barcode Scanner app for Android.  It’s nifty though it doesn’t take full advantage of my Droid’s camera resolution and there are some other tricks I’d like to see it do (such as activate the flash for improved lighting, replacing the constant autofocus with a forced focus, and perhaps adding some decoding protocols that aren’t supported in the Droid build of this, at least as of Barcode Scanner v3.1).  My main goal was to simply rebuild the app for the Android target via a Windows host, then play around with the code to learn more about Android coding.

I’d recently moved some install folders around so I decided to install the necessary parts from scratch.  Note that I first spent an hour or two trying to use Eclipse 3.5.1 to build this but haven’t gotten it to work (yet).  When I decided to try doing this via “basic principles” it quickly became apparent that this would take a while.

I ran into several issues I won’t bore you with here.  Suffice to say the answers are scattered around Google, either in the ZXing comments, discussions, or its bugs area, and sometimes completely elsewhere.  It became clear that while Windows is supported as a host it’s probably not the primary host they test builds from, so their instructions aren’t very current or coherent for it needed some tweaks, which they’ve made.  (Windows isn’t the most common way to build for Android but it’s quite do-able just the same.)

Here, then, is the distillation of what I learned in order to successfully build the Barcode Scanner app for Android via Windows. This should apply to other Windows versions as well, at least back to XP.  If you are using an x86-based Windows then use x86 installers instead of x64 installers (where there’s a difference).

# This is the setup for a Windows 7 host (64-bit on an Intel CPU)

# Install Sun JDK (jdk-6u18-windows-x##):
 - Source: http://java.sun.com/javase/downloads/index.jsp
    - Select the JDK appropriate to your Windows host (x64 or x86)
 - My root folder: "C:\Program Files\Java\jdk1.6.0_18"

# Install Sun WTK 2.5.2 (sun_java_wireless_toolkit-2.5.2_01-win.exe):
 - Yes, you need this too!
 - Source: http://java.sun.com/products/sjwtoolkit/
    - Select Sun Java Wireless Toolkit 2.5.2_01 for CLDC
 - My root folder: "C:\WTK2.5.2_01"

# WTK is NOT required for the Android target, but part of its folder structure IS, as follows.

# Install ProGuard Java Optimizer (proguard4.4.zip):
 - Source: http://sourceforge.net/projects/proguard/
 - My root folder: "D:\Programming\proguard4.4"

# Copy the proguard.jar file to the expected location in WTK:
 copy D:\Programming\proguard4.4\lib\proguard.jar C:\WTK2.5.2_01\bin
 - If the "C:\WTK2.5.2_01\bin" tree doesn't exist, simply create it and populate it as above
    (again, WTK itself is not required for the Android target)

# Install Apache Ant (apache-ant-1.8.0-bin):
 - Source: http://ant.apache.org/bindownload.cgi
 - My root folder: "D:\Programming\apache-ant-1.8.0"

# Install Google Android SDK (android-sdk_r04-windows):
 - Source: http://developer.android.com/sdk/index.html
 - My root folder: "D:\Programming\android-sdk-windows"

# Run "android-sdk-windows/SDK Setup":
 - Update all packages!

# Fix "dx.bat" for Android SDK pre-2.0 (it's broken in those):
 - More info in this thread
 cd /d D:\Programming\android-sdk-windows
 copy /y platforms\android-1.1\tools\dx.bat platforms\android-1.1\tools\dx.bat.ORIG
 copy /y platforms\android-2.0\tools\dx.bat platforms\android-1.1\tools
 copy /y platforms\android-1.5\tools\dx.bat platforms\android-1.5\tools\dx.bat.ORIG
 copy /y platforms\android-2.0\tools\dx.bat platforms\android-1.5\tools
 copy /y platforms\android-1.6\tools\dx.bat platforms\android-1.6\tools\dx.bat.ORIG
 copy /y platforms\android-2.0\tools\dx.bat platforms\android-1.6\tools

# Install the ZXing codebase (ZXing-1.4.zip):
 - Source: http://code.google.com/p/zxing/downloads/list
 - My root folder: "D:\Test\zxing-1.4"

# Edit "zxing-1.4\build.properties":
 - Note double-backslashes!
 - Update: WTK-home=C:\\WTK2.5.2_01
 - Update: android-home=T:\\Programming\\android-sdk-windows

Now, if all that went well you should be ready to build it!

# Open a "cmd.exe" window to work in.

# Set appropriate environment variables for the tools:
 set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_18
 set path=%PATH%;D:\Programming\android-sdk-windows\tools
 set path=%PATH%;D:\Programming\apache-ant-1.8.0\bin
 set path=%PATH%;%JAVA_HOME%\bin

# Set the environment variable for the root of your project:
 set MY_PROJ_ROOT=D:\Programming\workspace\zxing-1.4

# Running the build (repeat as necessary):
 REM I added this top-level clean step to my process -
 REM It helps when you have tried building from the wrong level!
 cd /d %MY_PROJ_ROOT%  &&  ant clean

 REM Standard build step (see note in android/build.xml)
 cd /d %MY_PROJ_ROOT%\core  &&  ant clean build-no-debug

 REM Debug is the default target - I prefer to name it explicitly
 cd /d %MY_PROJ_ROOT%\android  &&  ant clean debug

 REM OPTIONAL: You can instead build the release version but it's not signed
 cd /d %MY_PROJ_ROOT%\android  &&  ant clean release

# Inspect and use the build output (the APK file is produced if successful):
 - %MY_PROJ_ROOT%\android\bin

At this point you should have successfully built the Barcode Scanner app for Android!

Load it upon your emulator or phone and see how it works. To try it on your phone, you will probably need to uninstall the current version.  Then you will need to check the “Settings -> Applications -> Unknown Sources” box on your phone to install a debug binary like this (As always, be careful when testing in this mode!!)  Copy the APK to your phone and install it.  Voilà!  It worked for me.

Next steps:

  • Seeing if I can do this from within Eclipse.  A somewhat outdated Knol suggests this is possible, but I had no luck with it. Done!
  • Install a Subversion client to get the latest code and see how that goes (my expertise is with Clearcase and such so this should be interesting). Done!
  • Modifying some code! Done!

Disclaimer: I’m NOT attached to the ZXing project at all, I’m just putting this out there in the hopes that it’ll help others have an easier time at this than I did.  I probably cannot help you with any issues you have (especially for other host or target platforms).

7 Comments


  1. A few small replies which may clarify or help —

    Trust me, turning on the flash doesn’t work. The image comes out white at that range. We disable it explicitly on all devices, except the Behold 2 which doesn’t allow it.

    The issue is not resolution, but focus. The scanner actually only looks at the pixels you see on your screen — that’s about 0.07MP.

    And on that note, auto-focus is absolutely essential to a clean scan.

    You don’t need WTK unless you are trying to build the J2ME client.

    Yes none of us use Windows but I don’t know of any reason it wouldn’t work, except for Proguard, which doesn’t seem to work on Windows? You can build a non-optimized version or just switch to Linux.

    Yes, we’re not repeating instructions for setting up your development environment, since it’s not project-specific and kind of depends on your platform and preferred way of working.

    Reply

  2. I didn’t expect any replies this quickly – I especially didn’t expect one from one of the project leaders!

    Flash: yes, I see your point, though it’s more a point of curiosity for me (I think the Droid has variable brightness on this… it’s all as much about poking around just to poke around as anything else).

    Autofocus: I can see that, though the ability to fix on macro focus would seem useful for a camera with a macro setting (for close items mine doesn’t really sharpen up until it’s at the AF near-limit). I may experiment more with that just to see if it adds any value.

    I figured out how to adjust the viewfinder size. It’d be interesting to see that and the AF parameters as adjustable settings (is there no easy way to tell the native max resolution when planning for MAX_FRAME_WIDTH/HEIGHT?) It was nice having a larger field to work with.

    PDF417 was a curiosity too… I got that working – not a huge value in daily use and I can see how it can eat processing power but it was nice to see it works.

    All this comes back to the ability to build based on the information on the pages I found. In my experience, no information is better than wrong information, but if good info IS available it’s useful to have it out there. The Windows host build info is kinda broken, but as I’ve described it’s more in need of a bit of cleaning than anything else. Some things that stand out in my experience today:

    WTK: it appears you *have* to have it installed and available to build in Windows. I haven’t delved into exactly why this is but the build totally fails without it. This is probably directly related to the way Proguard is installed since it fails when looking for that (and when both are installed as and where expected it works fine). Perhaps Proguard can be installed in another place, but it’s apparently dependent on the WTK-home setting. Also, WTK 2.5.2_01 is apparently the default now (thanks to a security update). Looks like the default path in Windows changes a bit, while the Unix version doesn’t (though it is the updated version).

    build.properties – an example entry for android-home would be valuable, much like there is one for the other windows-possible entries. Likewise the WTK note above would be a useful (minor) fix to that Windows example path.

    Environment: I’ve tried to strip this down to the most basic configuration possible to build from Windows for Android. The Windows-host-build gaps I found were not numerous but they were critical to getting this to build for Android (the Eclipse gap is another story – if I figure out a simple solution I’ll post it but I’m just glad to be able to build it at all right now).

    Again, I spent a few hours hunting down all the extra bits and tweaks required to make this work. It’s not that the info is totally absent – it’s just scattered around in notes, comments and other places. Nor is it esoteric – what I did should be quite typical for most Windows hosts based on XP or later. Knowing what fundamental items are required to build for a given host/target combination is useful, and cleaning up and consolidating this info would be useful, especially to people who are new to a project (and especially with a Windows host – given that one must gather several bits together than might otherwise be standard in a “developer’s” install of Linux).

    I’m very glad there’s a Windows host option here – I just wanted to get the word out as to how a newbie might make use of it.

    Reply

  3. Did you ever get this to build and deploy to the phone from eclipse? If so I would be quite interested in hearing about how you did this.

    Cheers…

    Reply

  4. Not yet but I mean to look into that. If I make progress I’ll post a followup.

    Reply

  5. Great! I will be listening. They sell us on RAD development with eclipse, but it is such a haste getting anything to work… Android has a lot of complexity compared to other platforms. I am sure that that complexity will amount to more flexibility when it is mastered, but for now it is just to much to learn to be productive.

    Reply

  6. My main impulse for all of this is really more to learn about Android programming and refresh my build skills. I *have* gotten other little things working on Eclipse for Android, end-to-end, so I know it can be done for apps in general.

    In all fairness, the ZXing project appears to be command-line oriented, thus getting the current version of it building from within Eclipse might be a stretch, so I’m not going to beat my head against the wall too long in trying to get that to happen. The Knol I referred to claims it once worked, and now that I know more about the minimum requirements to build it I might have better luck but if not, oh well.

    Reply

  7. It was easier than I thought – I’ve created a new post with the Eclipse info!

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

*

This site uses Akismet to reduce spam. Learn how your comment data is processed.