1 #title JObjC
   2 #
   3 # Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved.
   4 # DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5 #
   6 # This code is free software; you can redistribute it and/or modify it
   7 # under the terms of the GNU General Public License version 2 only, as
   8 # published by the Free Software Foundation.  Oracle designates this
   9 # particular file as subject to the "Classpath" exception as provided
  10 # by Oracle in the LICENSE file that accompanied this code.
  11 #
  12 # This code is distributed in the hope that it will be useful, but WITHOUT
  13 # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 # FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 # version 2 for more details (a copy is included in the LICENSE file that
  16 # accompanied this code).
  17 #
  18 # You should have received a copy of the GNU General Public License version
  19 # 2 along with this work; if not, write to the Free Software Foundation,
  20 # Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  21 #
  22 # Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  23 # or visit www.oracle.com if you need additional information or have any
  24 # questions.
  25 #
  26 
  27 JObjC core provides a pure Java interface for calling C functions and
  28 sending ObjC messages. Given some information, it can marshal types
  29 automatically.
  30 
  31 It also parses BridgeSupport to generate Java wrappers around
  32 Framework bundles. These wrappers rely on the core to provide access
  33 to the C constants, enums, structs, functions, ObjC classes, etc of a
  34 framework.
  35 
  36 * How to build it
  37 
  38 Your best option is `ant all`. There's an Xcode "B&I" target that
  39 works for buildit.
  40 
  41 You'll need a recent JavaNativeFoundation, and perhaps some other
  42 things. Everything is usually there on SnowLeopard (or Leopard after
  43 the common ~javabuild/bin/update runs).
  44 
  45 The build process is quite involved. Xcode takes care of the native
  46 parts, ant takes care of the Java parts, and there's an unholy mix of
  47 external targets and hidden dependencies that keep Xcode and ant (and
  48 buildit on top of that) from stepping on each other. So a warning: the
  49 ant and Xcode targets don't have proper dependencies set up because of
  50 this. They have some dependencies configured, but not the entire
  51 chain. This is because of the jumping back and forth between
  52 externals. If you run the aggregate targets (Xcode B&I, ant all, ant
  53 test, ant bench), everything's is good. But if you manually invoke
  54 individual targets, chances are you'll miss something. Let's go over
  55 it all step by step:
  56 
  57 ** ant gen-pcoder
  58 
  59 The PrimitiveCoder subclasses have a lot of boiler plate which
  60 simplifies the generated MixedPrimitiveCoder classes. So instead of
  61 maintaining it, I maintain a tiny Haskell script that spits out the
  62 Java code. This ant target runs that script if Haskell is available on
  63 the system. If it isn't available, this will silently fail. That's
  64 okay, because chances are the PrimitiveCoder.java that you got from
  65 svn is current and does not need to be updated.
  66 
  67 ** ant build-core / Xcode build-core-java
  68 
  69 Build core simply builds the JObjC core java classes, and also
  70 generates headers for the JNI for Xcode.
  71 
  72 ** ant build-core-native / Xcode build-core-native
  73 
  74 Xcode builds the native core, using the headers from the Java core. It
  75 generates libJObjC.dylib.
  76 
  77 ** ant build-generator / Xcode build-generator-java
  78 
  79 ant builds the generator.
  80 
  81 ** ant run-generator / Xcode run-generator
  82 
  83 ant runs the generator, using the core Java and native classes.
  84 
  85 What is rungen? And what's run-generator-old? run-generator-old is the
  86 preferred way to run the generator from ant, but there's a strange bug
  87 when running from buildit that causes run-generator-old to
  88 freeze. Pratik was helping me debug it, inspecting the stack and
  89 snooping dtrace probes, but we never found the reason for the
  90 block. So I figured that maybe if I just add a layer of indirection
  91 maybe it'll work around that. And it did. Sad but true.
  92 
  93 ** ant build-generated / Xcode build-generated-java
  94 
  95 Build the generator output.
  96 
  97 ** ant build-additions / Xcode build-additions-java
  98 
  99 Builds java additions.
 100 
 101 ** ant build-additions-native / Xcode build-additions-native
 102 
 103 This builds a new version of libJObjC.dylib. It will rebuild
 104 everything from the core, and include everything from additions.
 105 
 106 ** ant assemble-product / Xcode assemble-product-java
 107 
 108 Create a jar, copy products to destination, etc.
 109 
 110 * How to test it
 111 
 112 The test cases also contain a Java component and a native component,
 113 and are built similarly to the above. The benchmarks are built
 114 together with the tests. So "ant build-test" and "ant
 115 build-test-native" will build both the benchmarks and the test. "ant
 116 test" will run the test. "ant bench" will run benchmarks. If you only
 117 want to run a specific benchmark, you can pass a regexp in the
 118 environment variable BENCH_MATCH.
 119 
 120 <src>
 121 ant test
 122 ant bench
 123 BENCH_MATCH=Foo ant bench
 124 </src>
 125 
 126 Test and bench reports will end up in
 127 build/JObjC.build/Debug/test-reports/
 128 
 129 * How to use it
 130 
 131 Include the jar in your classpath and set your java.library.path to
 132 the directory that contains the dylib. Same thing for app bundles.