Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update README and README-Branding.md, add LICENSE
- Loading branch information
1 parent
d5f0b18
commit e6b9075
Showing
3 changed files
with
99 additions
and
206 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| Copyright 2015 The New York Public Library, Astor, Lenox, and Tilden Foundations | ||
|
|
||
| Licensed under the Apache License, Version 2.0 (the "License"); you may not use | ||
| this file except in compliance with the License. You may obtain a copy of the | ||
| License at | ||
|
|
||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
|
|
||
| Unless required by applicable law or agreed to in writing, software distributed | ||
| under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR | ||
| CONDITIONS OF ANY KIND, either express or implied. See the License for the | ||
| specific language governing permissions and limitations under the License. | ||
|
|
||
| --- | ||
|
|
||
| This product includes code derived from the Readium Android SDK Launcher | ||
| (https://github.com/readium/SDKLauncher-Android) which is distributed under the | ||
| following license: | ||
|
|
||
| Copyright (c) 2014 Readium Foundation and/or its licensees. All rights reserved. | ||
|
|
||
| Redistribution and use in source and binary forms, with or without modification, | ||
| are permitted provided that the following conditions are met: | ||
|
|
||
| 1. Redistributions of source code must retain the above copyright notice, this | ||
| list of conditions and the following disclaimer. | ||
|
|
||
| 2. Redistributions in binary form must reproduce the above copyright notice, | ||
| this list of conditions and the following disclaimer in the documentation | ||
| and/or other materials provided with the distribution. | ||
|
|
||
| 3. Neither the name of the organization nor the names of its contributors may be | ||
| used to endorse or promote products derived from this software without | ||
| specific prior written permission. | ||
|
|
||
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND | ||
| ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | ||
| WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | ||
| DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR | ||
| ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | ||
| (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | ||
| LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON | ||
| ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||
| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
| SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,241 +1,83 @@ | ||
| Simplified | ||
| ========== | ||
| # Build Setup | ||
|
|
||
| ## IDE, Plugins, Versions, etc. | ||
| ## Java Prerequisites | ||
|
|
||
| ##### JDK 1.8 (min required 1.7) [download](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) | ||
| 1. You should have Java SE 8u101 or [a newer version of Java SE 8](http://www.oracle.com/technetwork/java/javase/downloads/index.html) installed. (Java SE 7u111 and newer versions of Java SE 7 may also work but have not been tested.) This is because older versions of Java do not trust [Let's Encrypt](https://letsencrypt.org/) which provides our SSL certificate. | ||
|
|
||
| ##### Maven 3.3.9 [download](https://maven.apache.org/download.cgi) | ||
| add settings.xml to .m2 directory | ||
| 2. The `JAVA_HOME` environment variable must be set correctly. You can check what it is set to in most shells with `echo $JAVA_HOME`. If that command does not show anything, adding the following line to `~/.profile` (assuming you are on macOS) and then executing `source ~/.profile` or opening a new shell should suffice: | ||
|
|
||
| request nexus credentials on slack [librarysimplified](https://librarysimplified.slack.com/messages/simplified-android/) | ||
|
|
||
| ``` | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <settings | ||
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
| xmlns="http://maven.apache.org/SETTINGS/1.0.0" | ||
| xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> | ||
| <servers> | ||
| <server> | ||
| <id>nypl-nexus-group</id> | ||
| <username>****</username> | ||
| <password>****</password> | ||
| </server> | ||
| </servers> | ||
| <profiles> | ||
| <profile> | ||
| <id>nypl</id> | ||
| //keystore for signing the app, remove this property if you don't have a keystore yet. | ||
| <properties> | ||
| <sign.keystore>****</sign.keystore> | ||
| <sign.alias>nypl</sign.alias> | ||
| <sign.storepass><![CDATA[****]]></sign.storepass> | ||
| <sign.keypass><![CDATA[****]]></sign.keypass> | ||
| </properties> | ||
| <repositories> | ||
| <repository> | ||
| <id>nypl-nexus-group</id> | ||
| <name>NYPL nexus repo group</name> | ||
| <url>https://nexus.librarysimplified.org:8443/nexus/content/groups/external</url> | ||
| <layout>default</layout> | ||
| </repository> | ||
| </repositories> | ||
| </profile> | ||
| </profiles> | ||
| <activeProfiles> | ||
| <activeProfile>nypl</activeProfile> | ||
| </activeProfiles> | ||
| </settings> | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
| ### Android Studio | ||
|
|
||
| [Download](http://tools.android.com/download/studio/builds/1-5) Version 1.5 of Android Studio. | ||
|
|
||
| ##### SDK Manager | ||
| Install at least the Android SDK Package 4.4.2 | ||
|
|
||
| ##### Other SDK Tools needed: | ||
| ``` | ||
| Android SDK Build Tools | ||
| Android SDK Tools | ||
| Android SDK Platform Tools | ||
| Local Maven repository for Support Libraries | ||
| Android Support Library | ||
| Google Play Service | ||
| Google Play APK Expansion Library | ||
| Google Play Licensing Library | ||
| Android NDK | ||
| ``` | ||
|
|
||
| ##### Environment Variables | ||
|
|
||
| ``` | ||
| export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_74.jdk/Contents/Home | ||
| export ANDROID_HOME=$HOME/Library/Android/sdk | ||
| export ANDROID_NDK_HOME=$ANDROID_HOME/ndk-bundle | ||
| export PATH=$PATH:$ANDROID_HOME/platform-tools/ | ||
| export PATH=$PATH:$HOME/Library/Maven/bin/ | ||
| ``` | ||
|
|
||
|  | ||
|
|
||
|
|
||
| #### Clone this repository or your forked repository | ||
|
|
||
|
|
||
| ##### Import cloned project | ||
|
|
||
|  | ||
|  | ||
|  | ||
|
|
||
|
|
||
| ##### Build Configuration | ||
|
|
||
| Select a Module: simplye, openebooks, vanilla... | ||
|
|
||
|  | ||
|
|
||
| Add a Maven goal with the following command. Any other goal which might be added automatically, should be removed. | ||
|
|
||
| ``` | ||
| -pl simplified-app-shared,simplified-app-simplye -am clean package -U -P nypl | ||
| ``` | ||
| ~~~w | ||
| # Replace NNN with your particular version of 1.8.0. | ||
| export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_NNN.jdk/Contents/Home | ||
| ~~~ | ||
|
|
||
| ``` | ||
| -pl simplified-app-shared,simplified-app-openebooks -am clean package -U -P nypl | ||
| ``` | ||
| 3. You can verify that everything is set up correctly by inspecting the results of both `java -version` and `javac -version`. | ||
|
|
||
| With Adobe DRM (NYPL and licensees only!) | ||
| ## Android Studio Prerequisites | ||
|
|
||
| ``` | ||
| -pl simplified-app-shared,simplified-app-simplye -am clean package -U -P nypl,nypl-drm-adobe | ||
| ``` | ||
| The latest version of Android Studio is strongly recommended. Versions older than 2.3.3 have not been tested. | ||
|
|
||
| ``` | ||
| -pl simplified-app-shared,simplified-app-openebooks -am clean package -U -P nypl,nypl-drm-adobe | ||
| ``` | ||
| ## Nexus Setup | ||
|
|
||
| Our application currently needs packages that are only available from our Nexus server in order to build correctly. (This will be changed in the future when non-DRM-enabled variants of the app are officially supported.) Nexus credentials can be obtained by emailing `nypl@winniequinn.com` or by asking in the `#simplified-android` channel of [librarysimplified.slack.com](https://librarysimplified.slack.com). | ||
|
|
||
| ### IntelliJ IDEA | ||
| [Download](https://www.jetbrains.com/idea/#chooseYourEdition), if you prefer using IntelliJ over Android Studio. | ||
| After setup with Android Studio, you can use IntelliJ going forward with the following modifications. | ||
| Once you have your credentials, the following lines must be added to `~/.gradle/gradle.properties`: | ||
|
|
||
| ##### Build Configuration | ||
| Make sure any other goal is removed, only the maven goal should remain. | ||
| ~~~ | ||
| # Replace USERNAME and PASSWORD appropriately. | ||
| # Do NOT use quotes around either value. | ||
| org.librarysimplified.nexus.username=USERNAME | ||
| org.librarysimplified.nexus.password=PASSWORD | ||
| ~~~ | ||
|
|
||
| ## Adobe Certificate Setup | ||
|
|
||
| The correct certificate file must be placed at `simplified-app-simplye/src/main/assets/ReaderClientCert.sig` in order for Adobe DRM to work. The app will function correctly without this file so long as only non-DRM-protected books are opened. | ||
|
|
||
| ## HelpStack Setup | ||
|
|
||
| **NOTE:** Care should always be taken to ensure HelpStack is functioning correctly after making any configuration changes. Configuration errors or a lack of configuration may result in errors that only appear at runtime. | ||
|
|
||
| ## Building | ||
| If HelpStack is to be used, a configuration file must be placed at `simplified-app-simplye/src/main/assets/helpstack.conf`. | ||
|
|
||
| #### Without DRM | ||
| For Zendesk, you should use the following configuration: | ||
|
|
||
| ``` | ||
| $ mvn clean package | ||
| helpstack.gear = zendesk | ||
| helpstack.zendesk.instance_url = ... | ||
| helpstack.zendesk.staff_email = ... | ||
| helpstack.zendesk.api_token = ... | ||
| ``` | ||
|
|
||
| #### With DRM (NYPL and licensees only!) | ||
|
|
||
| If the application is to be built with support for Adobe DRM, the | ||
| the Adobe-provided `ReaderClientCert.sig` files must be placed in | ||
| `src/main/assets` for each of the current application frontends. | ||
| The build will check for the existence of these files and fail if | ||
| they do not exist. | ||
|
|
||
| Once this is done, building the package with Adobe DRM support | ||
| enabled is achieved by: | ||
| For Salesforce Desk, use the following instead: | ||
|
|
||
| ``` | ||
| $ mvn -P nypl-drm-adobe clean package | ||
| helpstack.gear = desk | ||
| helpstack.desk.instance_url = ... | ||
| helpstack.desk.to_help_email = ... | ||
| helpstack.desk.staff_login_email = ... | ||
| helpstack.desk.staff_login_password = ... | ||
| ``` | ||
|
|
||
| ## HelpStack | ||
| ## Generating Signed APKs | ||
|
|
||
| If HelpStack is to be used, a configuration file must be provided | ||
| in the `assets` directory of the application being built. So, to | ||
| enable Zendesk for the `SimplyE` application, create a file at | ||
| `simplified-app-simplye/src/main/assets/helpstack.conf` with the | ||
| correct URL and credentials: | ||
| If you wish to generate a signed APK for publishing the application, you will need to set the following values correctly in `~/.gradle/gradle.properties`: | ||
|
|
||
| Configuration for Zendesk: | ||
|
|
||
| ``` | ||
| helpstack.gear = zendesk | ||
| helpstack.zendesk.instance_url = https://nonexistent.zendesk.com | ||
| helpstack.zendesk.staff_email = nobody@example.com | ||
| helpstack.zendesk.api_token = ************* | ||
| ``` | ||
| ~~~ | ||
| org.librarysimplified.simplye.keyAlias= | ||
| org.librarysimplified.simplye.keyPassword= | ||
| org.librarysimplified.simplye.storePassword= | ||
| ~~~ | ||
|
|
||
| Configuration for Desk.com: | ||
|
|
||
| ``` | ||
| helpstack.gear = desk | ||
| helpstack.desk.instance_url = https://nonexistent.desk.com | ||
| helpstack.desk.to_help_email = nobody@example.com | ||
| helpstack.desk.staff_login_email = nobody@example.com | ||
| helpstack.desk.staff_login_password = ************* | ||
| ``` | ||
| In addition, you will need to obtain the correct Java keystore and either place it in the project at `simplified-app-simplye/keystore.jks` or create a symbolic link at the same location appropriately. All files matching `*.jks` are set to be ignored by Git, but care should always be taken to ensure keystores and other secrets are never committed regardless. | ||
|
|
||
| ## Branding And Configurable Features | ||
|
|
||
| See [simplified-app-shared/README-Branding.md](simplified-app-shared/README-Branding.md) | ||
| for documentation on how to produce your own branded and configured | ||
| application. | ||
|
|
||
|
|
||
| ## License | ||
|
|
||
| ``` | ||
| © 2015 The New York Public Library, Astor, Lenox, and Tilden Foundations | ||
| Licensed under the Apache License, Version 2.0 (the "License"); | ||
| you may not use this file except in compliance with the License. | ||
| You may obtain a copy of the License at | ||
| http://www.apache.org/licenses/LICENSE-2.0 | ||
| for documentation on how to customize branding of the application. | ||
|
|
||
| Unless required by applicable law or agreed to in writing, software | ||
| distributed under the License is distributed on an "AS IS" BASIS, | ||
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express | ||
| or implied. See the License for the specific language governing | ||
| permissions and limitations under the License. | ||
| ``` | ||
| # Building | ||
|
|
||
| This product includes code derived from the [Readium Android SDK | ||
| Launcher](https://github.com/readium/SDKLauncher-Android), which | ||
| is distributed under the following license: | ||
| **NOTE:** Due to an unknown issue, you must execute `./gradlew assembleDebug` one time before opening the project in Android Studio. This will pull in all dependencies that, for whatever reason, are not fetched if Gradle is executed via Android Studio. | ||
|
|
||
| ``` | ||
| Copyright (c) 2014 Readium Foundation and/or its licensees. All rights reserved. | ||
| Redistribution and use in source and binary forms, with or without modification, | ||
| are permitted provided that the following conditions are met: | ||
| 1. Redistributions of source code must retain the above copyright notice, this | ||
| list of conditions and the following disclaimer. | ||
| 2. Redistributions in binary form must reproduce the above copyright notice, | ||
| this list of conditions and the following disclaimer in the documentation and/or | ||
| other materials provided with the distribution. | ||
| 3. Neither the name of the organization nor the names of its contributors may be | ||
| used to endorse or promote products derived from this software without specific | ||
| prior written permission. | ||
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND | ||
| ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | ||
| WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | ||
| IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, | ||
| INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, | ||
| BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||
| DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF | ||
| LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE | ||
| OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED | ||
| OF THE POSSIBILITY OF SUCH DAMAGE | ||
| ``` | ||
| After setup is complete, the project can be opened in Android Studio and built as normal. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters