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.