README 6.47 KB
Newer Older
1
To get started...
2

3 4 5 6 7 8
First, Bishop is built using Cordova, which is an HTML / CSS / JavaScript
development platform providing cross-platform support  for multiple devices.
Bishop uses SWORD as its Bible research engine, under the hood, which is C++,
and thus a native iOS and Android SWORD Cordova plugin has been published to
the standard Cordova plugin repository to provide this functionality on both
dominant mobile platforms.
9

10 11 12
The HTML / CSS / JavaScript for Bishop can be viewed and updated in a
limited capacity by simply pointing a Web Browser to bishop/www/index.html
e.g., using a URL something like:
13

14
file:///home/me/src/bishop/www/index.html
15

16
Because the native SWORD plugin won't be available through your web browser,
17 18 19 20 21
Bishop provides a mockup of the SWORD plugin to provide 'lorum ipsum' content
to help layout design with working on the HTML / CSS / JavaScript before
compiling for a phone or emulator.  This mockup functionality is very basic
and should be extended to include more functionality as needed.
You will find it at the top of www/js/bishop.js: localFixup
22

23 24 25 26 27 28 29 30 31 32 33 34 35
Beyond aesthetic changes, a full build of Bishop can be performed with
the information below:

A local development enviroment is ideal and usually requires some form of
bash command line functionality (Linux and macOS, installed by default;
Windows, provided with cygwin (https://www.cygwin.com/) or apparently as a
native install with newer versions of Windows:
https://itsfoss.com/install-bash-on-windows/ )

But if this is not possible, using an online build environment like
build.phonegap.com can provide build facilities
See ## Developing with build.phonegap.com ## later in this README

36

37 38
###### Full Development Setup #########################
 
39 40
###### Prerequisite #########################
# bishop is a cordova application
41
# and thus, prerequisite to compiling bishop is to have
42 43 44 45 46 47
# cordova successfully installed
# something like:
#
#   yum install npm
#   npm -g i cordova
#
48 49
# but see these links
# https://nodejs.org/en/download/
50
# https://cordova.apache.org/docs/en/latest/guide/cli/
51 52 53 54 55
#
# on iOS we use cordova-icon and cordova-splash to generate
# the plethora of required images.  You'll need to install
# these with something like:
#
56 57
#   sudo npm -g i cordova-icon
#   sudo npm -g i cordova-splash
58 59 60 61 62 63
#
# but see these links:
# https://github.com/AlexDisler/cordova-icon
# https://github.com/AlexDisler/cordova-splash
#

64 65 66 67
Bishop should mostly build with standard cordova commands. For example:
(replace 'ios' with 'android' if compiling for Android)

cordova platform add ios
68
# There currently seems to be a bug in recent versions of cordova
69 70 71 72 73 74 75 76 77 78 79 80
# for which the online community gives the workaround to simply remove
# and re-add the platform:
cordova platform rm ios
cordova platform add ios

cordova build --release
cordova run


If this doesn't work, a Makefile has been setup with most task targets.  Details
follow:

81 82 83

######## first time setup of bishop project after checkout ######################
# edit Makefile and choose target Android or iOS at the beginning of the Makefile
84
# then setup the project for your environment with
85 86
make setup

87
# to build 
88 89
make

90 91 92
# for iOS, the cli make doesn't complete successfully for me and
# it is necessary to finish the build in Xcode.
# Open in Xcode
93 94 95 96
# ~/src/bishop/platforms/ios/Bishop.xcodeproj
# then Product | Destination | [choose a simulator for testing]
# then Product | Build
# then the little VCR play button will run in emulator
97 98 99 100
#
# A nice feature of Safari in macOS is that it has a menu choice
# to attach to running iOS emulators and will allow you to debug
# the JavaScript in Bishop.
101

102 103
# for testing in Android
# and possibly iOS
104 105
make run

106 107 108 109 110 111 112 113 114 115 116
# if no phone is plugged in an emulator will be launched
# if your phone is plugged in, check to see that you can
# access it with something like:
adb devices #should show your phone
adb logcat #should tail the debug log on your phone

# if you don't have permission, you'll probably need to
# find the usb bus and dev of your phone and then:
sudo chmod 666 /dev/bus/usb/$bus/$dev
adb kill-server #restarts the adb server after permission change

117 118
# to simply install
make install
119

120 121 122 123 124

#########  Deploy Apple
#
# XCode: Product | Destination | Generic iOS Device
#	Product | Archive | Export... | Ad Hoc
125 126


127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159

########### Development with build.phonegap.com ##############

For scenarios where it is not possible to install a full development
environment, Bishop can still be improved by using an online build
farm service like build.phonegap.com.  Instructions follow:

1) Create a free GitHub account for your team. https://github.com

2) Create a new GitHub repository under your new account by importing
our official Bishop repository:

https://github.com/new/import

Our repository URL: http://git.crosswire.org/main/bishop.git

3) Create a free PhoneGap Build account: https://build.phonegap.com/

4) Add a free opensource app to your phonegap build account and provide your
new GitHub repository URL created in step 2. And try out a build.  It should
run successfully and produce Bishop binaries for both Android and Apple which
you can download and test on your own device (Android, at least; Apple makes
it a little more difficult to test (understatement))

We likely will continue to add features to Bishop, so you should consider
keeping your GitHub repository updated with our upstream official Bishop
repository to get the latest features. Something like:

git pull upstream master




160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
##########  Extending SWORD Cordova plugin ###############################
If, instead of using the released version of the SWORD cordova plugin,
you'd like to build it yourself....

Have sword checked out at the same level as bishop, e.g.,

cd ~/src
svn co https://crosswire.org/svn/sword/trunk sword
git clone http://git.crosswire.org/main/bishop.git

which shoule produce:

~/src/sword
~/src/bishop

##########  Prepare SWORD Cordova plugin ###############################
cd ~/src/sword/bindings/java-jni
make
cd ../Android
# run Android Studio and open project ~/src/sword/bindings/Android/SWORD
# once project is loaded, choose Build | Rebuild Project
# this will build the native libsword.so binaries for Android
# once building is complete, continue in shell...
make

# on iOS, build the cordova plugin libsword.so
# run Xcode and open project ~/src/sword/bindings/objc/SWORD/SWORD.xcodeproj
# select Product | Build
# then copy the universal libsword.so binary and deps with..
cd ~src/sword/bindings/objc
make


193
Again, thank you for partnering with us to share the Good New of our Lord Jesus Christ with a world desperate for Him.