-
Notifications
You must be signed in to change notification settings - Fork 54
/
README.developer
219 lines (179 loc) · 9.67 KB
/
README.developer
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
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
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
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
Purpose of this document
------------------------
This document is the starting point for developers that want to familiarize
themselves with the Little Go project, i.e. developers that are new to the
project, and also me, after I come back to the project after several months
or years :-)
Quick-start guide on how to build and run Little Go
---------------------------------------------------
The current build should work out of the box for Intel Macs, Xcode 15.1 and
the iOS base SDK 17.2 (read NOTES.Build if you need help setting up this
combination). If you want to build with a different setup (especially a Silicon
Mac or an older Xcode version) you will probably encounter errors. Consult
NOTES.build and NOTES.Build.3rdparty, but mostly you will be on your own.
Before you begin, make sure that you have CocoaPods installed on your machine.
Visit the CocoaPods website (https://cocoapods.org/) for instructions how to do
this. Also note that if you want to create a build that runs on an actual iOS
device there are additional requirements. See the section "Device builds" in
NOTES.build.
1. Log in as the user you are going to develop with.
2. Clone the Git repository. Note that downloading just the latest release
snapshot of the source code is not sufficient because the 3rdparty software
build depends on Git submodules.
3. Launch Terminal.app and execute these commands:
cd /path/to/littlego
git submodule update --init --recursive
./script/build-3rdparty-software.sh
4. Wait until the script has built all 3rdparty software packages (see the file
"NOTES.build.3rdparty" for more details), then execute this command:
pod install
5. Launch Xcode by opening "Little Go.xcworkspace"
6. Select the "Little Go Debug" scheme, and one of the iPhone or iPad simulator
destinations, from the toolbar's scheme selector
7. From the menu select Product > Run. The app should now be built in Debug
mode and launched inside the simulator.
Folder structure
----------------
<root>
+-- AUTHORS Principal authors and contributors of the project
+-- CONTRIBUTING.md The project's contributing guidelines.
+-- LICENSE The Apache license file.
+-- LICENSE.html The Apache license in HTML format (for display on the
| device).
+-- NOTICE Attribution notices.
+-- Podfile The CocoaPods configuration file.
+-- README.md Introduction to the project. This file is formatted in
| Markdown and rendered as the front page on GitHub.
+-- GoogleService-Info.plist This file is required for using the Crashlytics
| crash reporting service. The file is not under
| version control, you must create and populate it
| yourself with information from your own Firebase
| account. See section "Crash reporting" in
| NOTES.Diagnostics.
+-- 3rdparty After cloning the Little Go repository, this folder
| contains some of the 3rdparty software sources as Git
| submodules. After the 3rdparty software build, the
| folder also contains the build results.
+-- doc This folder contains documents not relevant for
| building the Little Go binary; some of these files are
| included in the application bundle that is distributed
| on the App Store.
+-- doxygen This folder contains a configuration file Doxyfile for
| Doxygen; the folder is intended to receive the files
| generated by Doxygen.
+-- resource This folder contains the project's resources such as
| image files for icons.
+-- script This folder contains command line scripts.
+-- sgf This folder contains .sgf files that are used for
| manual testing, demonstrating app features and creating
| marketing material. See the README file in the folder.
+-- src This folder contains the project's source code.
+-- test This folder contains the project's unit test files.
+-- uitest This folder contains the project's UI test files.
Document reference
------------------
Documents described here are located in the "doc" folder.
ReleaseSteps
This document lists the steps needed to make a project release.
ChangeLog
This document contains an annotated compilation of all bugfixes, newly
implemented features, and other improvements and changes for all released
versions of the project. The file is parsed and displayed in game under the
"Changelog" tab. For this to work, the content of this file must follow
certain guidelines that are documented in DocumentGenerator.h.
NOTES.Build
NOTES.Build.3rdparty
These documents have detailed notes about the third-party software build
process, and the project's own build process (including documentation about
any compiler warnings that currently exist).
NOTES.Architecture
NOTES.Design
littlego.asta
*.jpg
These documents contain some thoughts that went into architecture and design
of the project. There are also a few UML diagrams floating around as .jpg
files. The origin of these diagrams is the Astah project file littlego.asta.
To open that file you need to install the UML tool Astah - a free community
edition is available for download here: https://astah.net/
NOTES.Diagnostics
This document contains instructions what to do with the diagnostics
information file that is attached to bug report emails. It also contains
notes in regard to the Crashlytics crash reporting service.
NOTES.SgfSupport
This document has notes about the project's support for the SGF file format.
BUGS
This document contains notes about all known irregularities that are
currently in the project: Compiler warnings, Xcode analyze issues, runtime
messages printed to the Xcode debug console, unfixed crash reports, etc..
This document complements the issue list on the project's bug tracker.
TESTING
This document has information about how the project's automated testing
facilities work. It also contains a script for manual testing of most of the
application's features. The intent is to execute the script before a new
version is released to the App Store.
Other files
-----------
Little Go.xcworkspace
The Xcode workspace bundle. Open this, not the .xcodeproj bundle.
resource/plist/Info.plist
The information property list file that describes the Little Go application
bundle. Certain aspects of the Info.plist file are covered in more detail
in the document NOTES.Info-plist
script/build-3rdparty-software.sh
Helper script for downloading and building all 3rdparty software packages that
are required to build and run Little Go. See NOTES.Build.3rdparty for
details.
Version control
---------------
The version control system used to maintain this project is Git. The canonical
repository currently resides on GitHub:
- URL for cloning: git://github.com/herzbube/littlego.git
- URL for browsing: https://github.com/herzbube/littlego
The branching model adopted by the project is described in this article:
https://nvie.com/posts/a-successful-git-branching-model/.
Bugtracking
-----------
The bugtracker for the Little Go project is located on GitHub [1]. If you want
to submit a new issue you must be a registered GitHub user (it's free and they
won't bother you with spam!).
Before version 0.9.1, all issues were tracked on a private bugtracker [2]. If
you are really desperate about the project's history :-) you can browse the few
but closed bugs that are still floating around there.
[1] https://github.com/herzbube/littlego/issues
[2] https://bugs.herzbube.ch/
User manual
-----------
The application's user manual is maintained as a separate project on GitHub [1]
to avoid bloat of the source code repository due to large image files that can
potentially change with every new release of the app.
[1] https://github.com/herzbube/littlego-usermanual
Source code documentation with Doxygen
--------------------------------------
There is a "doxygen" target that can be used to transform the source code
documentation into a set of HTML files. The target uses a shell script that
assumes that Doxygen is installed in
/usr/local/bin
This is the standard path for the Homebrew project. If you have doxygen
installed somewhere else (e.g. /sw/bin, /opt/local/bin) you need to change the
target's shell script.
The Doxygen configuration file is located in
doxygen/Doxyfile
Notes about the configuration:
- Doxygen recursively searches for *.h, *.m and *.mm files in the project
top-level folder "src".
- Private methods declared in class extensions or categories in the .m files
are not included in the documentation process. Change this by setting
EXTRACT_LOCAL_METHODS = YES inside Doxyfile.
- Doxyfile is configured to look for the command line tool "dot" in
/usr/local/bin
dot is part of the Graphviz package and is used to generate a couple of
diagram types (e.g. class diagrams, collaboration diagrams).
On collaboration
----------------
Contributions in any form (coding, UI design, testing, bug reports, creating an
app video preview, website design) are, of course, very welcome!
Code contributors must have a certain level of experience with object-oriented
coding because I don't have enough spare time to offer a lot of training. I will
certainly coach and assist with getting the project to build and run, but a
certain tech-savyness as well as the will to learn Objective-C (the language
that this project is written in) is required.