Merge pull request #543 from madvay/faq0.5

FAQ for 0.5.0-alpha

FAQ.md

@@ -1,6 +1,10 @@
 # FAQ
 (for contributors, see [CONTRIBUTING.md](CONTRIBUTING.md))
 
+This FAQ only illustrates the most common ways to customize the J2ObjC Gradle Plugin.  See
+[J2objcConfig.groovy](https://github.com/j2objc-contrib/j2objc-gradle/blob/master/src/main/groovy/com/github/j2objccontrib/j2objcgradle/J2objcConfig.groovy)
+for comprehensive documentation of all options.
+
 __Table of Contents__
 <!--
 To update the TOC,
@@ -18,27 +22,28 @@ Paste the results below, replacing existing contents.
 - [How do I develop with Xcode?](#how-do-i-develop-with-xcode)
 - [How can I speed up my build?](#how-can-i-speed-up-my-build)
 - [What libraries are linked by default?](#what-libraries-are-linked-by-default)
+- [How do I setup dependencies with J2ObjC?](#how-do-i-setup-dependencies-with-j2objc)
 - [What should I add to .gitignore?](#what-should-i-add-to-gitignore)
 - [What is the recommended folder structure for my app?](#what-is-the-recommended-folder-structure-for-my-app)
 - [What tasks does the plugin add to my project?](#what-tasks-does-the-plugin-add-to-my-project)
-- [What version of Gradle do I need?](#what-version-of-gradle-do-i-need)
-- [How do I solve the Eclipse error message Obtaining Gradle model...?](#how-do-i-solve-the-eclipse-error-message-obtaining-gradle-model)
-- [How do I properly pass multiple arguments to J2ObjC?](#how-do-i-properly-pass-multiple-arguments-to-j2objc)
+- [How do I customize translation with J2ObjC?](#how-do-i-customize-translation-with-j2objc)
+- [How do I customize compilation and linkage?](#how-do-i-customize-compilation-and-linkage)
 - [Why is my clean build failing?](#why-is-my-clean-build-failing)
 - [How do I include Java files from additional source directories?](#how-do-i-include-java-files-from-additional-source-directories)
 - [How do I develop with Swift?](#how-do-i-develop-with-swift)
 - [How do I solve 'File not found' import error in Xcode?](#how-do-i-solve-file-not-found-import-error-in-xcode)
 - [How do I work with Package Prefixes?](#how-do-i-work-with-package-prefixes)
-- [How do I enable ARC for my Objective-C classes?](#how-do-i-enable-arc-for-my-objective-c-classes)
+- [How do I enable ARC for my translated Objective-C classes?](#how-do-i-enable-arc-for-my-translated-objective-c-classes)
 - [How do I call finalConfigure()?](#how-do-i-call-finalconfigure)
-- [Why is my Android build so much slower after adding j2objc?](#why-is-my-android-build-so-much-slower-after-adding-j2objc)
+- [Why is my Android build so much slower after adding J2ObjC?](#why-is-my-android-build-so-much-slower-after-adding-j2objc)
 - [Error: implicit declaration of function 'JreRelease' is invalid in C99 [-Werror,-Wimplicit-function-declaration] JreRelease(this$0_)](#error-implicit-declaration-of-function-jrerelease-is-invalid-in-c99--werror-wimplicit-function-declaration-jrereleasethis0_)
 - [How do I disable a plugin task?](#how-do-i-disable-a-plugin-task)
-- [How do I setup dependencies with J2ObjC?](#how-do-i-setup-dependencies-with-j2objc)
 - [Cycle Finder Basic Setup](#cycle-finder-basic-setup)
 - [Cycle Finder Advanced Setup](#cycle-finder-advanced-setup)
 - [How do I develop on Windows or Linux?](#how-do-i-develop-on-windows-or-linux)
 - [How do I fix missing required architecture linker warning?](#how-do-i-fix-missing-required-architecture-linker-warning)
+- [How do I solve the Eclipse error message Obtaining Gradle model...?](#how-do-i-solve-the-eclipse-error-message-obtaining-gradle-model)
+
 
 ### Start here for debugging (aka it's not working; aka don't panic)
 
@@ -74,11 +79,19 @@ Now try building again.
 
 ### How do I develop with Xcode?
 
-When using the `j2objcTask`, open the `.xcworkspace` file in Xcode. If the `.xcodeproj` file
+The J2ObjC Gradle Plugin configures your Xcode project with [CocoaPods](https://cocoapods.org/).
+To take advantage of this, specify the directory that contains `PROJECT.xcodeproj` as
+the `xcodeProjectDir` in your `j2objcConfig` per the [Quick Start Guide](README.md#quick-start-guide).
+
+After running `j2objcXcode`, 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-IOS-APP-j2objc-shared
 
+If you don't use CocoaPods, do not specify the `xcodeProjectDir` option;
+you'll have to manually add the static libraries and translated header directories
+to your Xcode project, and `j2objcXcode` will not do anything.
+
 Also see the FAQ note on [developing with Swift](#how-do-i-develop-with-swift).
 
 
@@ -117,11 +130,30 @@ The standard libraries are:
     org.mockito:mockito-core (test only)
     org.hamcrest:hamcrest-core (test only)
 
+Note that this only covers the Objective-C libraries; if you want to use these
+libraries in your Java code, you must still include the standard dependency directives like:
+
+```gradle
+// shared/build.gradle
+dependencies {
+    compile 'com.google.guava:guava:18.0'
+    testCompile 'junit:junit:4.11'
+}
+```
+
+
+### How do I setup dependencies with J2ObjC?
+
+The plugin can handle many types of dependencies: multiple Java projects, external libraries and
+unit-tests (with source), existing Objective-C code, etc.
+
+See [dependencies.md](dependencies.md).
+
 
 ### What should I add to .gitignore?
 
 The .gitignore file should follow existing conventions for Android Studio and Xcode.
-Once that's configured, check it contains the following:
+Once that's configured, check that it contains the following:
 
     # Includes j2objc.home setting (Android Studio should have added this)
     local.properties
@@ -166,34 +198,25 @@ shown before folders, so it is not in strict alphabetical order.
 
 ### What tasks does the plugin add to my project?
 
-These are the main tasks for the plugin:
+The main tasks for the plugin are:
 
-    j2objcCycleFinder - Find memory cycles that can cause leaks, see FAQ for more details
     j2objcTranslate   - Translates Java source to Objective-C
-    j2objcAssemble    - Outputs packed libraries, source & resources to build/j2objcOutputs
+    j2objcAssemble    - Outputs built libraries, source & resources to 'build/j2objcOutputs'
     j2objcTest        - Runs all JUnit tests in the translated code
-    j2objcBuild       - Runs j2objcAssemble and j2objcTest, doesn't run j2objcXcode
-    j2objcXcode       - Xcode updated with libraries, headers & resources (uses CocoaPods)
-
-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`.
+    j2objcXcode       - Updates Xcode project with translated libraries, headers & resources (uses CocoaPods)
+    j2objcBuild       - Runs j2objcTranslate, j2objcAssemble, j2objcTest, and j2objcXcode
 
+Running the `build` task from the Gradle Java plugin will automatically run the `j2objcBuild` task
+and all the previous tasks (which it depends on).  The `j2objcXcode` task will disable itself
+automatically if no `xcodeProjectDir` is specified.
 
-### What version of Gradle do I need?
+Note that you can use the Gradle shorthand of `$ gradlew jA` to do the `j2objcAssemble` task.
 
-You need at least [Gradle version 2.4](https://discuss.gradle.org/t/gradle-2-4-released/9471),
-due to support for native compilation features.
 
+### How do I customize translation with J2ObjC?
 
-### How do I solve the Eclipse error message ``Obtaining Gradle model...``?
-
-You have to first create the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
-Go to your project folder and do ``gradle wrapper``. Refresh your Eclipse project.
-
-
-### How do I properly pass multiple arguments to J2ObjC?
+Inside your `j2objcConfig` section, you can pass any of the [options J2ObjC takes](http://j2objc.org/docs/j2objc.html)
+with `translateArgs`.
 
 Make sure your arguments are separate strings, not a single space-concatenated string.
 
@@ -212,10 +235,24 @@ j2objcConfig {
 ```
 
 
+### How do I customize compilation and linkage?
+
+Many well-known compiler or linker args can be customized using an existing
+`J2objcConfig` option.  The plugin already sets up a standard build for you,
+so only configure these options if the defaults fail to work.
+
+As a last resort, inside your `j2objcConfig` section, you can pass any of the
+standard Clang compiler or linker args as `extraObjcCompilerArgs` and `extraLinkerArgs`,
+respectively.
+
+Make sure your arguments are separate strings, not a single space-concatenated strings
+(see `translateArgs` example above).
+
+
 ### 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
+if you don't have any JUnit 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
@@ -261,6 +298,7 @@ you'd like to access from Swift code. Also see the FAQ item on [file not found](
 #import "MyClassTwo.h"
 ```
 
+
 ### How do I solve 'File not found' import error in Xcode?
 
 This is typically caused by a limitation of Xcode that expects all the source to be in a
@@ -274,6 +312,10 @@ j2objcConfig {
 }
 ```
 
+If you'd like to preserve your folder hierarchy, you can instead change your 
+[USER_HEADER_SEARCH_PATHS](https://developer.apple.com/library/mac/documentation/DeveloperTools/Reference/XcodeBuildSettingRef/1-Build_Setting_Reference/build_setting_ref.html#//apple_ref/doc/uid/TP40003931-CH3-SW21)
+setting in your Xcode projects to include the `shared/build/j2objcOutputs/src/main/objc` folder.
+
 Example error:
 
 ```
@@ -303,19 +345,23 @@ j2objcConfig {
 // File: resources/prefixes.properties
 // Storing at this location allows Class.forName(javaName) to work for mapped class.
 com.example.dir: Ced
-com.example.dir.subdir: Ceds
+com.example.dir.subdir: Ced
 ```
 
-As of J2ObjC verion 0.9.8 you can also use wildcards in your prefixes file. 
-This will map packages such as com.example.dirandcom.example.dir.subdir both to Ceds.
+You can also use wildcards in your prefixes file. 
+This will map packages such as com.example.dir and com.example.dir.subdir both to Ced.
 
 ```
-com.example.dir.*: Ceds
-````
+com.example.dir.*: Ced
+```
 
-### How do I enable ARC for my Objective-C classes?
+### How do I enable ARC for my translated Objective-C classes?
 
-Add the following to your configuration block. [See](https://developer.apple.com/library/mac/releasenotes/ObjectiveC/RN-TransitioningToARC/Introduction/Introduction.html#//apple_ref/doc/uid/TP40011226-CH1-SW15).
+__Note__: The use of ARC for the translated code is not recommended and is not required
+in order to use ARC for the hand-written Objective-C iOS app that links to the translated code.
+
+Add the following to your configuration block. See 
+[here](https://developer.apple.com/library/mac/releasenotes/ObjectiveC/RN-TransitioningToARC/Introduction/Introduction.html#//apple_ref/doc/uid/TP40011226-CH1-SW15).
 
 ```gradle
 j2objcConfig {
@@ -338,8 +384,11 @@ j2objcConfig {
 }
 ```
 
+In addition, put your `j2objcConfig` at the very end of your build.gradle.  This allows
+`finalConfigure()` to correctly access other project settings, like dependencies.
+
 
-### Why is my Android build so much slower after adding j2objc?
+### Why is my Android build so much slower after adding J2ObjC?
 
 Depending on your Android Studio 'run configuration', you may be building more of your Gradle
 project than is neccessary.  For example if your run configuration includes a general 'Make'
@@ -354,7 +403,7 @@ make sure you are running `./gradlew :android:assembleDebug` and not for example
 
 ### Error: implicit declaration of function 'JreRelease' is invalid in C99 [-Werror,-Wimplicit-function-declaration] JreRelease(this$0_)
 
-See: [How do I enable ARC for my Objective-C classes?](#how-do-i-enable-arc-for-my-objective-c-classes?)
+See: [How do I enable ARC for my translated Objective-C classes?](#how-do-i-enable-arc-for-my-translated-objective-c-classes?)
 
 
 ### How do I disable a plugin task?
@@ -365,18 +414,14 @@ disable the `j2objcTest` task, do the following:
 
 ```gradle
 // File: shared/build.gradle
-j2objcTest {
-    enabled = false
-}
 j2objcConfig {
     ...
 }
-```
-
 
-### How do I setup dependencies with J2ObjC?
-
-See [dependencies.md](dependencies.md).
+j2objcTest {
+    enabled = false
+}
+```
 
 
 ### Cycle Finder Basic Setup
@@ -435,7 +480,7 @@ For more details:
 
 ### How do I develop on Windows or Linux?
 
-Windows and Linux support is limited to the j2objcCycleFinder and j2objcTranslate tasks.
+Windows and Linux support is limited to the `j2objcCycleFinder` and `j2objcTranslate` tasks.
 Mac OS X is required for the j2objcAssemble, j2objcTest and j2objcXcode tasks
 (see [task descriptions](README.md#tasks)) This matches the
 [J2ObjC Requirements](http://j2objc.org/#requirements).
@@ -475,3 +520,9 @@ j2objcConfig {
     supportedArchs += ['ios_i386']
 }
 ```
+
+
+### How do I solve the Eclipse error message ``Obtaining Gradle model...``?
+
+You have to first create the [Gradle wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html).
+Go to your project folder and do ``gradle wrapper``. Refresh your Eclipse project.

README.md

@@ -40,7 +40,7 @@ Configure `shared/build.gradle` for your Java-only project:
 // File: shared/build.gradle
 plugins {
     id 'java'
-    id 'com.github.j2objccontrib.j2objcgradle' version '0.4.3-alpha'
+    id 'com.github.j2objccontrib.j2objcgradle' version '0.5.0-alpha'
 }
 
 dependencies {