Merge pull request #328 from brunobowden/docs

Docs: initial user experience + refactor project dependencies

Author: brunobowden

FAQ.md

@@ -33,9 +33,9 @@ Make sure your arguments are separate strings, not a single space-concatenated s
 
 ### Why is my clean build failing?
 
-This is a [known issue](https://github.com/j2objc-contrib/j2objc-gradle/issues/306) if you don't
-have any tests.
-If you are doing `./gradlew clean build`, try instead `./gradlew clean && ./gradlew build`.
+This is a [known issue](https://github.com/j2objc-contrib/j2objc-gradle/issues/306)
+if you don't have any tests. If you are doing `./gradlew clean build`, try instead
+`./gradlew clean && ./gradlew build`.
 
 When you don't have any test source files, The plugin creates a placeholder to force the
 creation of a test binary; this is done during project configuration phase, but `clean` deletes
@@ -44,10 +44,10 @@ this file before `build` can use it.
 
 ### How do I include Java files from additional source directories?
 
-In order to include source files from sources different than ``src/main/java`` you have to
+In order to include source files from sources different than `src/main/java` you have to
 [modify the Java plugin's sourceSet(s)](https://docs.gradle.org/current/userguide/java_plugin.html#N11FD1).
-For example, if you want to include files from ``src-gen/base`` both into your JAR and (translated) into
-your Objective C libraries, then add to your ``build.gradle``:
+For example, if you want to include files from `src-gen/base` both into your JAR and (translated) into
+your Objective C libraries, then add to your `shared/build.gradle`:
 
     sourceSets {
         main {
@@ -64,16 +64,16 @@ To work with Swift in Xcode, you need to configure a [bridging header](https://d
 Within that bridging header, include the file needed for using the JRE and any classes that you'd like
 to access from Swift code.
 
-```
-// File: IOS-APP-bridging-header.h
+    // File: ios/IOS-APP/IOS-APP-bridging-header.h
 
-// Required for Swift initialization of Java objects (they all inherit from JavaObject)
-#import "JreEmulation.h"
+    // J2ObjC requirement for Java Runtime Environment
+    // Included from /J2OBJC_HOME/include
+    #import "JreEmulation.h"
 
-// Swift accessible j2objc translated classes, referenced from `shared/build/j2objcOutputs/src/main/objc`
-#import "MyClassOne.h"
-#import "MyClassTwo.h"
-```
+    // Swift accessible J2ObjC translated classes
+    // Included from `shared/build/j2objcOutputs/src/main/objc`
+    #import "MyClassOne.h"
+    #import "MyClassTwo.h"
 
 
 ### How do I enable ARC for my Objective-C classes?
@@ -89,7 +89,7 @@ Add the following to your configuration block. [See](https://developer.apple.com
 ### How do I call finalConfigure()?
 
 You must always call `finalConfigure()` at the end of `j2objcConfig {...}` within your project's
-`build.gradle` file. You need to include an otherwise empty j2objcConfig { } block with this
+`build.gradle` file. You need to include an otherwise empty `j2objcConfig {...}` block with this
 call even if you do not need to customize any other `j2objConfig` option.
 
     j2objcConfig {
@@ -106,60 +106,71 @@ See: [How do I enable ARC for my Objective-C classes?](#how-do-i-enable-arc-for-
 ### How do I disable a plugin task?
 
 You can disable tasks performed by the plugin using the following configuration block in your
-`build.gradle`. This is separate and alongside the j2objcConfig settings. For example, to
+`build.gradle`. This is separate and alongside the `j2objcConfig` settings. For example, to
 disable the `j2objcTest` task, do the following:
 
+    // File: shared/build.gradle
     j2objcTest {
         enabled = false
     }
-
     j2objcConfig {
         ...
     }
 
 
-### How do I setup multiple related J2ObjC or native projects?
+### How do I setup dependencies with J2ObjC?
 
-You can express three kinds of dependencies within j2objcConfig:
+See the following FAQ answers...
 
-1. The common case is that Java and j2objc Project B depends on Java and J2ObjC Project A,
-and you need the Project B J2ObjC generated library to depend on the Project A J2ObjC
-generated library. In this case add to B.gradle:
 
-```
+### How do I setup a dependency on a Gradle Java project?
+
+If project `shared` depends on Gradle Java Project A, and you want J2Objc generated Project
+`shared` to depend on J2ObjC generated Project A. Add to `shared/build.gradle`:
+
+    // File: shared/build.gradle
     j2objcConfig {
         dependsOnJ2objc project(':A')
     }
-```
 
-This kind of dependency should be inferred automatically from the corresponding Java
-dependency in the future.
+Project A needs to have the J2objc Gradle Plugin applied and the `j2objcConfig` with the
+`finalConfigure()` call. This applies transitively, so in turn it may need `dependsOnJ2objc`
+again. Alternatively you can try building using `--build-closure` (TODO: need item on this).
+The library will be linked in and the headers available for inclusion. Project A will be
+built first.
 
-2. Java and j2objc project B depends on a
-[custom native library](https://docs.gradle.org/current/userguide/nativeBinaries.html#N15F82)
-called someLibrary in native project A.  Add to B.gradle:
+In the future, this kind of dependency should be inferred automatically from the corresponding
+Java dependency - [issue 41](https://github.com/j2objc-contrib/j2objc-gradle/issues/41).
 
-```
-    j2objcConfig {
-        extraNativeLib project: ':A', library: 'someLibrary', linkage: 'static'
-    }
-```
 
-3. Java and j2objc project B depends on library libpreBuilt pre-built outside of
-Gradle in directory /lib/SOMEPATH, with corresponding headers in /include/SOMEPATH.
-Add to B.gradle:
+### How do I setup a dependency on a prebuilt native library?
 
-```
+For a Java and J2ObjC project `shared` that depends on library libpreBuilt pre-built outside
+of Gradle in directory /lib/SOMEPATH, with corresponding headers in /include/SOMEPATH.
+Add to `shared/build.gradle`:
+
+    // File: shared/build.gradle
     j2objcConfig {
         extraObjcCompilerArgs '-I/include/SOMEPATH'
         extraLinkerArgs '-L/lib/SOMEPATH'
         extraLinkerArgs '-lpreBuilt'
     }
-```
 
-In (1) and (2), A's library will be linked in and A's headers will be available for inclusion, and
-B will automatically build after A.  (3) is not supported by Gradle's dependency management
-capabilities; you must ensure preBuilt's binary and headers are available before project B is built.
+The library will be linked in and the headers available for inclusion. All prebuilt libraries
+must be fat binaries with the architectures defined by `supportedArchs` in
+[j2objcConfig.groovy](https://github.com/j2objc-contrib/j2objc-gradle/blob/master/src/main/groovy/com/github/j2objccontrib/j2objcgradle/J2objcConfig.groovy).
+
+
+### How do I setup a dependency on a Gradle native library project?
+
+If project `shared` depends on a
+[custom native library](https://docs.gradle.org/current/userguide/nativeBinaries.html#N15F82)
+called someLibrary from native project A. Add to `shared/build.gradle`:
+
+    // File: shared/build.gradle
+    j2objcConfig {
+        extraNativeLib project: ':A', library: 'someLibrary', linkage: 'static'
+    }
 
 
 ### Cycle Finder Basic Setup
@@ -173,6 +184,7 @@ The basic setup will implicitly check for 40 memory cycles - this is the expecte
 of erroneous matches with `jre_emul` library for J2ObjC version 0.9.6.1. This may cause
 issues if this number changes with future versions of J2ObjC libraries.
 
+    // File: shared/build.gradle
     j2objcCycleFinder {
         enabled = true
     }
@@ -194,10 +206,11 @@ and building the J2ObjC source:
 
     `(cd jre_emul && make java_sources_manifest)`
 
-3. Configure j2objcConfig in build.gradle so CycleFinder uses the annotated J2ObjC source
-and whitelist. Note how this gives and expected cycles of zero.
+3. Configure j2objcConfig in `shared/build.gradle` so CycleFinder uses the annotated J2ObjC
+source and whitelist. Note how this gives and expected cycles of zero.
 
 ```
+    // File: shared/build.gradle
     j2objcConfig {
         cycleFinderArgs '--whitelist', 'J2OBJC_REPO/jre_emul/cycle_whitelist.txt'
         cycleFinderArgs '--sourcefilelist', 'J2OBJC_REPO/jre_emul/build_result/java_sources.mf'

README.md

@@ -15,13 +15,18 @@ At HEAD, this plugin is in a state of significant flux as we refactor it into a
 Gradle plugin for our beta. You may wish to wait for the beta release as we may make backwards
 incompatible changes before that point.
 
-You should start with a clean java only project without any android dependencies. It suggested that
-this project is named `'shared'`. It must be buildable using Gradle's standard `'java'` plugin.
-It may start as an empty project and allows you to gradually shift over code from an existing
-Android application. See the section below on [Folder Structure](#folder-structure).
+You should start with a clean java only project without any android dependencies.
+It is suggested that the project is named `shared`. It must be buildable using the standard
+[Gradle Java plugin](https://docs.gradle.org/current/userguide/java_plugin.html).
+Starting as an empty project allows you to gradually shift over code from an existing
+Android application. This if beneficial for separation between the application model
+and user interface and a project which can easily be used server side as well.
 
-This is how to configure the build.gradle in your java only project. Please follow the link to
-find the latest version number of the plugin:
+The Android app, shared Java project and Xcode should be sibling directories, i.e children
+of the same root level folder. Suggested names are `android, shared & ios` respectivey.
+See the section below on [Folder Structure](#folder-structure).
+
+Configure `shared/build.gradle` in your Java only project:
 
     // File: shared/build.gradle
     plugins {
@@ -31,61 +36,117 @@ find the latest version number of the plugin:
 
     // Plugin settings:
     j2objcConfig {
-        xcodeProjectDir '../ios'  // Xcode workspace directory
-        xcodeTarget 'IosApp'      // iOS app target name
+        xcodeProjectDir '../ios'  // Xcode workspace directory (suggested name)
+        xcodeTarget 'IOS-APP'     // iOS app target name (replace with existing app name)
 
         // Other Settings:
         // https://github.com/j2objc-contrib/j2objc-gradle/blob/master/src/main/groovy/com/github/j2objccontrib/j2objcgradle/J2objcConfig.groovy#L30
 
         finalConfigure()          // Must be last call to configuration
     }
 
-Within the Android application's project `build.gradle`, make it dependent on the `shared` project:
+Within the Android application's `android/build.gradle`, make it dependent on
+the `shared` project:
 
     // File: android/build.gradle
     dependencies {
         compile project(':shared')
     }
 
 
+### J2ObjC Installation
+
+Download the latest version from the [J2ObjC Releases](https://github.com/google/j2objc/releases).
+Find the local.properties in your root folder and add the path to the unzipped folder:
+
+    // File: local.properties
+    j2objc.home=/J2OBJC_HOME
+
+
+### Build Commands
+
+The plugin will output the generated source and libaries to the `build/j2objcOutputs`
+directory. It is integrated with Gradle's Java build plugin and may be run as follows:
+
+    ./gradlew shared:build
+
+To update an existing Xcode project to load the libraries and header files, use this
+additional command:
+
+    ./gradlew shared:j2objcXcode
+
+Typically they should both be used together:
+
+    ./gradlew shared:build shared:j2objcXcode
+
+
 ### NOTE: Open .xcworkspace in Xcode
 
-When using the j2objcXcodeTask, open the `.xcworkspace` file in Xcode. If the `.xcodeproj` file
+When using the `j2objcTask`, open the `.xcworkspace` file in Xcode. If the `.xcodeproj` file
 is opened in Xcode then CocoaPods will fail. This will appear as an Xcode build time error:
 
     library not found for -lPods-*-j2objc-shared
 
+Also see the FAQ note on [developing with Swift](https://github.com/j2objc-contrib/j2objc-gradle/blob/master/FAQ.md#how-do-i-develop-with-swift).
+
+
+### Build Speed
+
+You can reduce the build time by 50% by skipping the release binaries by adding the
+following to your root level `local.properties` file:
+
+    j2objc.release.enabled=false
+
+This is helpful for a tight modify-compile-test loop and using only debug binaries.
+You can also do this for `j2objc.debug.enabled`.
+
+
+### J2ObjC Standard Libraries
+
+A number of standard libraries are included with the J2ObjC releases and linked
+by default when using the plugin. To add other libraries, see the FAQ
+[dependency on a Java project](FAQ.md#how-do-i-setup-a-dependency-on-a-java-project).
+The standard libraries are:
+
+    guava
+    javax_inject
+    jsr305
+    junit
+    mockito
+    protobuf_runtime - TODO: https://github.com/j2objc-contrib/j2objc-gradle/issues/327
+
 
 ### Folder Structure
 
 This is the suggested folder structure. It also shows a number of generated files and
-folders that aren't committed to your repository. Files are shown before folders, so it
-is not in strict alphabetical order.
+folders that aren't committed to your repository (marked with .gitignore). Files are
+shown before folders, so it is not in strict alphabetical order.
 
     workspace
-    ├── .gitignore                     // Should exclude: local.properties, settings.gradle, build/, ...
+    ├── .gitignore                     // Add Ignores: local.properties, build/, Pod/
     ├── build.gradle
-    ├── local.properties               // sdk.dir=<Android SDK> and j2objc.home=<J2ObjC>, .gitignore exclude
+    ├── local.properties               // sdk.dir=<Android SDK> and j2objc.home=<J2ObjC>, .gitignore
     ├── settings.gradle                // include ':android', ':shared'
     ├── android
     │   ├── build.gradle               // dependencies { compile project(':shared') }
     │   └── src/...                    // src/main/java/... and more, only Android specific code
     ├── ios
-    │   ├── iosApp.xcworkspace         // Xcode workspace
-    │   ├── iosApp.xcodeproj           // Xcode project, which is modified by j2objcXcode / CocoaPods
+    │   ├── IOS-APP.xcworkspace        // Xcode workspace
+    │   ├── IOS-APP.xcodeproj          // Xcode project, which is modified by j2objcXcode / CocoaPods
     │   ├── Podfile                    // j2objcXcode modifies this file for use by CocoaPods, committed
-    │   ├── iosApp/...                 // j2objcXcode configures dependency on j2objcOutputs/{libs|src}
-    │   ├── iosAppTests/...            // j2objcXcode configures as above but with "debug" buildType
-    │   └── Pods/...                   // generated by CocoaPods for Xcode, .gitignore exclude
+    │   ├── IOS-APP/...                // j2objcXcode configures dependency on j2objcOutputs/{libs|src}
+    │   ├── IOS-APPTests/...           // j2objcXcode configures as above but with "debug" buildType
+    │   └── Pods/...                   // generated by CocoaPods for Xcode, .gitignore
     └── shared
         ├── build.gradle               // apply 'java' then 'j2objc' plugins
-        ├── build                      // generated build directory, .gitignore exclude
+        ├── build                      // generated build directory, .gitignore
         │   ├── ...                    // other build output
         │   ├── binaries/...           // Contains test binary: testJ2objcExecutable/debug/testJ2objc
         │   ├── j2objc-shared.podspec  // j2objcXcode generates these settings to modify Xcode
         │   └── j2objcOutputs/...      // j2objcAssemble copies libraries and headers here
         ├── lib                        // library dependencies, must have source code for translation
-        │   └── lib-with-src.jar       // library with source can be translated
+        │   ├── lib-with-src.jar       // library with source can be translated, see FAQ on how to use
+        │   └── libpreBuilt.a          // library prebuilt for ios, see FAQ on how to use
         └── src/...                    // src/main/java/... shared code for translation
 
 
@@ -100,20 +161,12 @@ These are the main tasks for the plugin:
     j2objcBuild             - Runs j2objcTest and j2objcAssemble, doesn't run j2objcXcode
     j2objcXcode             - Xcode updated with libraries, headers & resources (uses CocoaPods)
 
-Note that you can use the Gradle shorthand of `$ gradlew jA` to do the `j2objcAssemble` task.
+Running the `build` task from the Gradle Java plugin will automatically run the j2objcBuild command
+and all the previous tasks (which it depends on). Only the `j2objcXcode` task needs to be manually
+run. Note that you can use the Gradle shorthand of `$ gradlew jA` to do the `j2objcAssemble` task.
 The other shorthand expressions are `jCF, jTr, jA, jTe, jB and jX`.
 
 
-### Faster Development Cycle
-
-If you are developing in a tight modify-compile-test loop and using only debug binaries, you
-may want to disable the release build temporarily by adding to your `local.properties` file:
-
-    j2objc.release.enabled=false
-
-This should cut the J2ObjC build time up to 50%.  You can also do this for `j2objc.debug.enabled`.
-
-
 ### FAQ
 
 See [FAQ.md](FAQ.md).
@@ -125,5 +178,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#quick-start).
 
 ### License
 
-This library is distributed under the Apache 2.0 license found in the
-[LICENSE](./LICENSE) file.
+This library is distributed under the Apache 2.0 license found in the [LICENSE](./LICENSE) file.