diff --git a/README.md b/README.md index 1edbb1ced..892ce38c4 100644 --- a/README.md +++ b/README.md @@ -18,11 +18,11 @@ The repo is structured in the following projects (ordered by dependencies): * **build/project-template** - this is an empty placeholder Android Application project, used by the [NativeScript CLI](https://github.com/NativeScript/nativescript-cli) when building an Android project. # Build Prerequisites -The source in this repo is organized in Android Studio projects. +Following are the minimal prerequisites to build the runtime package. * Install the latest [Android Studio ](https://developer.android.com/studio/index.html). -* Install Android API Level 22 from Android Studio -> Tools -> Android -> SDK Manager -* Install the Android NDK from Android Studio -> Tools -> Android -> SDK Manager +* Install Android API Level 22, 23, 24, 25 from Android Studio -> Tools -> Android -> SDK Manager +* Android NDK 12b - [NDK Archives](https://developer.android.com/ndk/downloads/older_releases.html) * Download Android Support Repository through the Android SDK Manager * Download Build Tools 25.0.2 through the Android SDK Manager. diff --git a/docs/test-cli-app-howto/3rd-party-plugins.png b/docs/test-cli-app-howto/3rd-party-plugins.png new file mode 100644 index 000000000..d8a293c5f Binary files /dev/null and b/docs/test-cli-app-howto/3rd-party-plugins.png differ diff --git a/docs/test-cli-app-howto/add-binaries.png b/docs/test-cli-app-howto/add-binaries.png new file mode 100644 index 000000000..6580764ea Binary files /dev/null and b/docs/test-cli-app-howto/add-binaries.png differ diff --git a/docs/test-cli-app-howto/align-versions.png b/docs/test-cli-app-howto/align-versions.png new file mode 100644 index 000000000..cf35bed7e Binary files /dev/null and b/docs/test-cli-app-howto/align-versions.png differ diff --git a/docs/test-cli-app-howto/config-debugger-tab.png b/docs/test-cli-app-howto/config-debugger-tab.png new file mode 100644 index 000000000..9a2e5aa6d Binary files /dev/null and b/docs/test-cli-app-howto/config-debugger-tab.png differ diff --git a/docs/test-cli-app-howto/edit-configurations.png b/docs/test-cli-app-howto/edit-configurations.png new file mode 100644 index 000000000..3bfd41f8a Binary files /dev/null and b/docs/test-cli-app-howto/edit-configurations.png differ diff --git a/docs/test-cli-app-howto/final-binaries.png b/docs/test-cli-app-howto/final-binaries.png new file mode 100644 index 000000000..4a4481690 Binary files /dev/null and b/docs/test-cli-app-howto/final-binaries.png differ diff --git a/docs/test-cli-app-howto/open-project.png b/docs/test-cli-app-howto/open-project.png new file mode 100644 index 000000000..c7192445d Binary files /dev/null and b/docs/test-cli-app-howto/open-project.png differ diff --git a/docs/test-cli-app-howto/open-settings.png b/docs/test-cli-app-howto/open-settings.png new file mode 100644 index 000000000..3b1628de8 Binary files /dev/null and b/docs/test-cli-app-howto/open-settings.png differ diff --git a/docs/test-cli-app-howto/select-project.png b/docs/test-cli-app-howto/select-project.png new file mode 100644 index 000000000..89395246b Binary files /dev/null and b/docs/test-cli-app-howto/select-project.png differ diff --git a/docs/test-cli-app-howto/set-compile-sdk.png b/docs/test-cli-app-howto/set-compile-sdk.png new file mode 100644 index 000000000..cfac5b933 Binary files /dev/null and b/docs/test-cli-app-howto/set-compile-sdk.png differ diff --git a/docs/test-cli-app-howto/set-ndk.png b/docs/test-cli-app-howto/set-ndk.png new file mode 100644 index 000000000..c3bd78d9e Binary files /dev/null and b/docs/test-cli-app-howto/set-ndk.png differ diff --git a/test-cli-app/.gitignore b/test-cli-app/.gitignore index d630dc072..9b7278b97 100644 --- a/test-cli-app/.gitignore +++ b/test-cli-app/.gitignore @@ -1,3 +1,15 @@ +*.iml +.gradle +/local.properties +/.idea/workspace.xml +/.idea/libraries +.DS_Store /build -/src -proguard-rules.pro \ No newline at end of file +/captures +app/build +app/src/* +app/.iml +app/proguard-rules.pro +!app/build.gradle +!app/src/.gitkeep +gradle-app.setting \ No newline at end of file diff --git a/test-cli-app/README.md b/test-cli-app/README.md new file mode 100644 index 000000000..afc7fac45 --- /dev/null +++ b/test-cli-app/README.md @@ -0,0 +1,52 @@ +# Debugging NativeScript CLI app with the Hybrid (Java and CPP) debugger in Android Studio + +## Prerequisites: + - [Android Studio](https://developer.android.com/studio/index.html#downloads) + - Android SDK (Can be managed through the SDK Manager in AS) + - Android Platform 23, 24, 25 + - Android Support Repository + - Build Tools *25.0.2* + - Android NDK 12b - [NDK Archives](https://developer.android.com/ndk/downloads/older_releases.html) + + +## First Launch + - Open Android Studio - Click `Open an existing Android Studio project` + - ![Open existing AS project](../docs/test-cli-app-howto/open-project.png) + - Select the `test-cli-app` Gradle project and click `OK` + - ![Select project](../docs/test-cli-app-howto/select-project.png) + - Next configure the path to the Android NDK. This allows compilation and debugging of the native code (the runtime contains predominantly C++ code). `File -> Project Structure...` (`Ctrl+Alt+Shift+S`) + - ![Open settings](../docs/test-cli-app-howto/open-settings.png) + - Set the Android NDK location to point to your `12b` extracted NDK package on a hard drive. If prompted - **Do not** install latest NDK. + - ![Set NDK](../docs/test-cli-app-howto/set-ndk.png) + + ## Configuring the project + - Build a NativeScript application using the CLI (`tns build android`) + - Navigate to `my-app/platforms/android/`, copy the `src` directory to `test-cli-app/app/` + - Align the `model.android.compileSdkVersion` to match the one used when building your project (default - highest installed, or one passed with the `--compileSdk` flag) + - ![Set compileSdk](../docs/test-cli-app-howto/set-compile-sdk.png) + - Align the support library versions so that the big version (first number) matches that of the compileSdk + - ![Align versions](../docs/test-cli-app-howto/align-versions.png) + - > **IMPORTANT**: If the project refers to any gradle plugins (additional support library plugins, sidedrawers, design library, google play libraries, 3rd party libraries etc.) either in `my-app/app/app.gradle`, or in any of the nativescript plugins installed in the application, those references will need to be included manually in the `test-cli-app/app/build.gradle` file's `dependencies` scope. + + - Illustration of the above: using the `nativescript-drawingpad` in a project, it is required to refer the jcenter `"com.github.gcacace:signature-pad"` package: + - ![3rd Party libs](../docs/test-cli-app-howto/3rd-party-plugins.png) + - Build the entire project to ensure everything is setup properly, and the runtime is ready to be debugged - `Build -> Rebuild Project` + + + ## Configuring debug symbols for debugging C++ code +- **Note:** The following needs to be done only once. The paths to the binary directories are stored locally. Add the necessary symbols that will allow your applications to break in native (C++) code +- Click on the `app` project -> `Edit Configurations`... + - ![Edit configurations](../docs/test-cli-app-howto/edit-configurations.png) +- On the settings window that opens up click on the `Debugger` tab + - ![Debugger tab](../docs/test-cli-app-howto/config-debugger-tab.png) +- Click the `+` (plus) button and proceed by adding the directories with the symbol tables for x86 and armeabi-v7a ABIs. This will ensure that whether the application debugged is an x86 emulator, or an armeabi-v7a device, C++ breakpoints will be hit. + - ![Add Binaries](../docs/test-cli-app-howto/add-binaries.png) +- Ultimately the `Debugger/Symbol Directories` tab should end up looking like this: + - ![Final look binaries](../docs/test-cli-app-howto/final-binaries.png) + + + +## Debugging the project +Click the Play/Debug icon beneath the Android Studio Toolbar to run yourNativeScript app using the locally built runtime. Any changes made to the`runtime` subproject will be reflected immediately on following installations(runs) of the app through the AS UI. + +In addition to debugging of the runtime bits, AS provides a clean and usefulUI to monitor the device Logcat. (Alt-6) will open the `Android Monitor` tool. diff --git a/test-cli-app/app/build.gradle b/test-cli-app/app/build.gradle new file mode 100644 index 000000000..1590ae425 --- /dev/null +++ b/test-cli-app/app/build.gradle @@ -0,0 +1,108 @@ +def isWinOs = System.properties['os.name'].toLowerCase().contains('windows') + +apply plugin: 'com.android.model.application' + +def runOnDevice = project.hasProperty("runOnDevice"); +def runOnDeviceOrEmulator = runOnDevice ? "-d" : "-e"; + +model { + android { + compileSdkVersion = 25 + buildToolsVersion = "25.0.2" + + defaultConfig.with { + applicationId = "com.tns.debugapp" + minSdkVersion.apiLevel = 17 + targetSdkVersion.apiLevel = 25 + versionCode = 1 + versionName = "1.0" + } + + lintOptions.with { + abortOnError = false + } + } + +// android.ndk { +// moduleName = "test-app-dummy-native-lib" +// } + + android.buildTypes { + release { + minifyEnabled = false + proguardFiles.add(file('proguard-rules.txt')) + } + } +} + +dependencies { + def supportVer = "25.3.1" + compile project(':runtime') + compile fileTree(include: ['*.jar'], dir: 'libs') + + compile "com.android.support:support-v4:$supportVer" + compile "com.android.support:appcompat-v7:$supportVer" + compile "com.android.support:design:$supportVer" + + testCompile 'junit:junit:4.12' +} + +repositories { + jcenter() + flatDir { + dirs 'src/F0', 'src/F1', + 'src/F2', 'src/F3', + 'src/F4', 'src/F5', + 'src/F6', 'src/F7', + 'src/F8', 'src/F9', + 'src/F10', 'src/F11' + } +} + +task addAarDependencies { + FileTree tree = fileTree(dir: "$projectDir/src", include: ["**/*.aar"]) + tree.each { File file -> + def length = file.name.length() - 4 + def fileName = file.name[0.. - // remove the extension of the file (.aar) - def length = file.name.length() - 4 - def fileName = file.name[0.. \(.*\)$'` + if expr "$link" : '/.*' > /dev/null; then + PRG="$link" + else + PRG=`dirname "$PRG"`"/$link" + fi +done +SAVED="`pwd`" +cd "`dirname \"$PRG\"`/" >/dev/null +APP_HOME="`pwd -P`" +cd "$SAVED" >/dev/null + +CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar + +# Determine the Java command to use to start the JVM. +if [ -n "$JAVA_HOME" ] ; then + if [ -x "$JAVA_HOME/jre/sh/java" ] ; then + # IBM's JDK on AIX uses strange locations for the executables + JAVACMD="$JAVA_HOME/jre/sh/java" + else + JAVACMD="$JAVA_HOME/bin/java" + fi + if [ ! -x "$JAVACMD" ] ; then + die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." + fi +else + JAVACMD="java" + which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. + +Please set the JAVA_HOME variable in your environment to match the +location of your Java installation." +fi + +# Increase the maximum file descriptors if we can. +if [ "$cygwin" = "false" -a "$darwin" = "false" ] ; then + MAX_FD_LIMIT=`ulimit -H -n` + if [ $? -eq 0 ] ; then + if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then + MAX_FD="$MAX_FD_LIMIT" + fi + ulimit -n $MAX_FD + if [ $? -ne 0 ] ; then + warn "Could not set maximum file descriptor limit: $MAX_FD" + fi + else + warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT" + fi +fi + +# For Darwin, add options to specify how the application appears in the dock +if $darwin; then + GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\"" +fi + +# For Cygwin, switch paths to Windows format before running java +if $cygwin ; then + APP_HOME=`cygpath --path --mixed "$APP_HOME"` + CLASSPATH=`cygpath --path --mixed "$CLASSPATH"` + JAVACMD=`cygpath --unix "$JAVACMD"` + + # We build the pattern for arguments to be converted via cygpath + ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null` + SEP="" + for dir in $ROOTDIRSRAW ; do + ROOTDIRS="$ROOTDIRS$SEP$dir" + SEP="|" + done + OURCYGPATTERN="(^($ROOTDIRS))" + # Add a user-defined pattern to the cygpath arguments + if [ "$GRADLE_CYGPATTERN" != "" ] ; then + OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)" + fi + # Now convert the arguments - kludge to limit ourselves to /bin/sh + i=0 + for arg in "$@" ; do + CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -` + CHECK2=`echo "$arg"|egrep -c "^-"` ### Determine if an option + + if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then ### Added a condition + eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"` + else + eval `echo args$i`="\"$arg\"" + fi + i=$((i+1)) + done + case $i in + (0) set -- ;; + (1) set -- "$args0" ;; + (2) set -- "$args0" "$args1" ;; + (3) set -- "$args0" "$args1" "$args2" ;; + (4) set -- "$args0" "$args1" "$args2" "$args3" ;; + (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;; + (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;; + (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;; + (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;; + (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;; + esac +fi + +# Split up the JVM_OPTS And GRADLE_OPTS values into an array, following the shell quoting and substitution rules +function splitJvmOpts() { + JVM_OPTS=("$@") +} +eval splitJvmOpts $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS +JVM_OPTS[${#JVM_OPTS[*]}]="-Dorg.gradle.appname=$APP_BASE_NAME" + +exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@" diff --git a/test-cli-app/gradlew.bat b/test-cli-app/gradlew.bat new file mode 100644 index 000000000..8a0b282aa --- /dev/null +++ b/test-cli-app/gradlew.bat @@ -0,0 +1,90 @@ +@if "%DEBUG%" == "" @echo off +@rem ########################################################################## +@rem +@rem Gradle startup script for Windows +@rem +@rem ########################################################################## + +@rem Set local scope for the variables with windows NT shell +if "%OS%"=="Windows_NT" setlocal + +@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. +set DEFAULT_JVM_OPTS= + +set DIRNAME=%~dp0 +if "%DIRNAME%" == "" set DIRNAME=. +set APP_BASE_NAME=%~n0 +set APP_HOME=%DIRNAME% + +@rem Find java.exe +if defined JAVA_HOME goto findJavaFromJavaHome + +set JAVA_EXE=java.exe +%JAVA_EXE% -version >NUL 2>&1 +if "%ERRORLEVEL%" == "0" goto init + +echo. +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:findJavaFromJavaHome +set JAVA_HOME=%JAVA_HOME:"=% +set JAVA_EXE=%JAVA_HOME%/bin/java.exe + +if exist "%JAVA_EXE%" goto init + +echo. +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% +echo. +echo Please set the JAVA_HOME variable in your environment to match the +echo location of your Java installation. + +goto fail + +:init +@rem Get command-line arguments, handling Windowz variants + +if not "%OS%" == "Windows_NT" goto win9xME_args +if "%@eval[2+2]" == "4" goto 4NT_args + +:win9xME_args +@rem Slurp the command line arguments. +set CMD_LINE_ARGS= +set _SKIP=2 + +:win9xME_args_slurp +if "x%~1" == "x" goto execute + +set CMD_LINE_ARGS=%* +goto execute + +:4NT_args +@rem Get arguments from the 4NT Shell from JP Software +set CMD_LINE_ARGS=%$ + +:execute +@rem Setup the command line + +set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar + +@rem Execute Gradle +"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS% + +:end +@rem End local scope for the variables with windows NT shell +if "%ERRORLEVEL%"=="0" goto mainEnd + +:fail +rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of +rem the _cmd.exe /c_ return code! +if not "" == "%GRADLE_EXIT_CONSOLE%" exit 1 +exit /b 1 + +:mainEnd +if "%OS%"=="Windows_NT" endlocal + +:omega diff --git a/test-cli-app/runtimedebug.iml b/test-cli-app/runtimedebug.iml deleted file mode 100644 index 6544dbcaf..000000000 --- a/test-cli-app/runtimedebug.iml +++ /dev/null @@ -1,118 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/test-cli-app/settings.gradle b/test-cli-app/settings.gradle new file mode 100644 index 000000000..2b3e9868d --- /dev/null +++ b/test-cli-app/settings.gradle @@ -0,0 +1,4 @@ +include ':binding-generator', ':runtime', ':app' + +project(':binding-generator').projectDir = new File("../", "binding-generator") +project(':runtime').projectDir = new File("../", "runtime") \ No newline at end of file