-----
Intro
-----

OK people, this is my first time releasing the sources for such a complex project.
So please cut me some slack if not everything is perfect yet.
Also most choices for it have been made 7-8 years ago, starting the project
today some things would likely not look the same.
Anyway - it's been one hell of a ride creating and releasing this stuff, I hope
you enjoy the result!

Have fun

- Michael

----------------
Downloading
----------------
See http://www.irrgheist.com/hcraftsource.htm for getting the newest sources.

The media has to be placed in a folder called media_hc1 which must be besides the h-craft folder.
The name of the h-craft folder doesn't matter, but we use trunk_hc1 in this document.
So you have for example:
my_home/trunk_hc1
my_home/media_hc1

Then the media must be copied once more for development. 
Open a bash console and go into the build folder. There call:
copy-media-linux.sh or copy-media-mingw.sh (depending on which system you are using).
In the end you should have:
my_home/trunk_hc1/media

The media inside hcraft can be used for development - so configuration files are changed, user data is added.
The media_hc1 folder is important to do clean releases without any development data left in it.
I keep them synchronized by doing a diff on the folders once in a while.

---------------
Requirements PC
---------------
H-Craft needs a GNU toolchain. The only compiler supported is gcc and the library build-scripts need the bash.
Not sure which gcc versions will do, but gcc 4.7.2 works here and older gcc versions worked previously as well.

On Windows you have to install MinGW to get a GNU toolchain. Cygwin is not supported so far.
Only tested with MinGW32 so far, so no experience with 64 bit on Windows yet. For 64-bit MinGW we would have
to replace at least libgcc_s_dw2-1.dll and libstdc++-6.dll. If anyone knows a way to automate copying of 
those dll's so we can remove them from the hg repository please tell me (bash-script instead would be nice).
Also only Windows 7 was tested so far.

On Linux you should have most of the gnu-toolchain installed already. You might have to add a 'gcc' package.

You need CMake to compile the libs.

The project files are currently made for the Code::Blocks IDE (http://www.codeblocks.org/).
I am working with nightly builds of Code::Blocks.
It's probably possible to get other build-environments working, but to start out using the GNU toolchain + Code::Blocks IDE is likely the easiest.

I'm not sure right now about the system library dependencies. But you need at least system libraries and OpenGL.

----------------
Build PC - Linux
----------------
Libraries:

In a bash console go into the hcraft1/build folder.
Call make-libs-linux.sh
If there are any errors report them and we might be able to figure out what's going on.

Start the Code::Blocks IDE and open libs/irrlicht/source/Irrlicht/Irrlicht-gcc.cbp
Select as target Linux Release - accurate math - static
Build it.

H-Craft:
In the Code::Blocks IDE open src/hover.cbp
Select the corresponding Linux target and click build.

------------------
Build PC - Windows
------------------
Libraries:

In a bash console go into the trunk_hc1/build folder.
Call make-libs-mingw.sh
If there are any errors report them and we might be able to figure out what's going on.

Start the Code::Blocks IDE and open libs/irrlicht/source/Irrlicht/Irrlicht-gcc.cbp
Select as target: Win32 Release - accurate math - dll
Build it.

H-Craft:
In the Code::Blocks IDE open src/hover.cbp
Select the corresponding mingw target and click build.

------------------
Doing PC releases:
------------------
x compile with -DNDEBUG and without profile
x compile Irrlicht with optimized settings (-s -O2 -fexpensive-optimizations, on 32-bit use -march=i686)
. set settings in compile_config.h (HOVER_RELEASE 1)
. full version: HOVER_DEMO 0 in compile_config.h
. compile hcraft with optimized settings (-s -O2 -fexpensive-optimizations, on 32-bit use -march=i686)
. call the release script in /tools
. check file folders
. same for demo: HOVER_DEMO 1 in compile_config.h
. test the release
. Need to update any websites?
. Make a backup for each version released to the public

x check executable flags. All files copied from Windows partition will have it set (which is wrong)
Compress Demo with:
	zip hcraft_demo.zip -9 -r hcraft_demo/
Release with password:
	zip hcraft.zip -e -9 -r hcraft/
	zip hcraft_demo.zip -e -9 -r hcraft_demo/
Release without password:
	zip hcraft.zip -9 -r hcraft/

Remove for system specific versions (works only when the files are decompressed on the system!)
Windows full: zip -r -d hcraft_windows.zip hcraft/libs hcraft/hcraft hcraft/hcraft_bin
Windows demo: zip -r -d hcraft_demo_windows.zip hcraft_demo/libs hcraft_demo/hcraft hcraft_demo/hcraft_bin
Linux full: zip -d hcraft_linux.zip hcraft/*.exe hcraft/*.dll
Linux demo: zip -d hcraft_demo_linux.zip hcraft_demo/*.exe hcraft_demo/*.dll

Merge system version:
diff -qr linux/hcraft windows/craft
Copy the files from Windows to Linux which Linux version didn't have.
chmod -x *.dll in the main folder.

--------------------
Requirements Android
--------------------
To use Android you need to have installed:
- Android SDK (from http://developer.android.com)
- Android NDK (from http://developer.android.com)
- ant (a build tool commonly used for Java)
- A Java jdk (for example openjdk-6-jdk)
- GNU Make 3.81 or later
- A recent version of awk

Android development was done completely on a Linux-Debian system, no other OS has been tried. 
The only compiler supported is gcc. Not sure which gcc versions will do, but gcc 4.7.2 works here.
In theory Windows+Cygwin could also be used for Android development, but I never tried to get that running.

The packages installed in the Android SDK Manager (which you can start on console with "android sdk"):
- Tools - Android SDK Tools
- Tools - Android SDK Platform-tools
- Tools - Android SDK Build-tools
- Android 5.1.1 (API22) - Documentation for Android SDK
- Android 5.1.1 (API22) - SDK Platform
- Android 5.1.1 (API21) - Sources for Android SDK (likely not needed)
- Android 3.2 (API13) - SDK Platform
- Android 3.2 (API13) - Samples for SDK (likely not needed)
- Android 3.2 (API13) - Google API's
- Android 3.2 (API13) - Google TV Addon (likely not needed)
- (also most System Images, but only used those to check emulator, so maybe not needed)
- Extras - Android Support Library
- Extras - Google Play services
- Extras - Google Repository
- Extras - Google Play APK Expansion Library
- Extras - Google Play Billing Library
- Extras - Google Play Licensing Library
- Extras - Google Web Driver

The following changes should be added to your .bashrc file, 
where <install_path> must be replaced by your corresponding path 
and versions numbers might differ (Google updates often):
export ANDROID_HOME=<install_path>/android/adt-bundle-linux-x86_64-20131030/sdk
export ANDROID_NDK=<install_path>/android/android-ndk-r10c
export ANDROID_BUILD_TOOLS=$ANDROID_HOME/build-tools/22.0.1
And add those to your PATH: $ANDROID_HOME/tools:$ANDROID_HOME/platform-tools:$ANDROID_BUILD_TOOLS:$ANDROID_NDK

Also add an export to your .bashrc for the folder where you have put hcraft:
export HCRAFT_HOME=<hcraft1_folder>

Lastly - you need at least one Android device. If you want to try out some emulators that's fine by me.
But the official emulator will be too slow to work with and too slow to run a gles2 game.

-------------
Build Android
-------------
Libraries:
In a bash console go into the hcraft1/build folder.
Call make-libs-android.sh
If there are any errors report them and we might be able to figure out what's going on.

Go into libs/irrlicht_ogl-es/source/Irrlicht/Android and call:
ndk-build NDEBUG=1

It's generally easier to do most Android development on PC (faster debugging & testing).
For that you can also build all libraries like described above for Linux.
And then build the libs/irrlicht_ogl-es/source/Irrlicht/Irrlicht-gcc.cbp 
As target I recommend "Linux - debug - static" as this is mostly used for debugging.
You also need to have OpenGL ES2 on your system for that. Some mesa package does have that.

H-Craft:
The things which need to be done for Android are:
- Make sure all media is in the build/android/assets folder as that is the one copied to the Android phones.
- Compile the c++ sources
- Compile the java sources and create a .apk file
- In release the .apk needs to be signed and zipalign'ed.
- Upload the package to the mobile phone
- Show the debug info on PC while running it on the phone.

My solution is to put some aliases in my .bashrc:
alias n0='rm -rf $HCRAFT_HOME/build/android/assets; cp -r $HCRAFT_HOME/media $HCRAFT_HOME/build/android/assets; cp -r $HCRAFT_HOME/shaders $HCRAFT_HOME/build/android/assets/shaders;cp -r $HCRAFT_HOME/tests $HCRAFT_HOME/build/android/assets/tests;'
alias n1='ndk-build V=1 NDK_DEBUG=1'
alias n2='ant debug'
alias n3='adb -d install bin/hcraft1-debug.apk'
alias n4='adb -d logcat -c;adb logcat Irrlicht:V DEBUG:V *:S'
alias n12='n1 && n2'
alias n123='n1 && n2 && n3'
alias n1234='n1 && n2 && n3 && n4'
alias n234='n2 && n3 && n4'
alias n34='n3 && n4'

alias nr0='rm -rf $HCRAFT_HOME/build/android/assets; ln -s $HCRAFT_HOME/../media_hc1/media $HCRAFT_HOME/build/android/assets; ln -s $HCRAFT_HOME/shaders $HCRAFT_HOME/build/android/assets/shaders'
alias nr1='ndk-build NDEBUG=1 V=1 NDK_DEBUG=0 HOVER_RELEASE=1'
alias nr2='ant release'
alias nr3='jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore test.keystore bin/hcraft1-release-unsigned.apk test -tsa http://timestamp.digicert.com'
alias nr4='rm bin/hcraft1-release.apk; zipalign -v 4 bin/hcraft1-release-unsigned.apk bin/hcraft1-release.apk'
alias nr5='adb -d install bin/hcraft1-release.apk'
alias nr12='nr1 && nr2'

Most aliases expect to be run from within the build/Android folder.
n is normal nr is for release builds.
n0, nr0 are to copy the media folders and shaders. That has only to be run when the media changed or you switch between debug and release.
n1, nr1 build the c++ code
n2, nr2 build the Java .apk
nr3 is for signing (see below in "Doing Android releases" what this is about - you have to create a key-store first and adapt this alias to it by replacing the 'test' parts)
nr4 is for running zipalign
n3, nr5 are for uploading the .apk to the Android device
n4 is for running a log showing all Irrlicht and DEBUG messages while silencing all other messages.
The combination numbers (like n1234) are to run several commands in a row.
Notice that adb returns always 0 - even on failure - so n3 and nr5 always return 0 (meaning n34 will always run n4 as well even if n3 failed).

For a typical rebuild + debug session I type: n1234

----------------------
Doing Android releases
----------------------
Still learning this myself... 

Signing apps:
1. Create the Rekey, for example:
keytool -genkey -v -keystore test.keystore -alias test -keyalg RSA -keysize 2048 -validity 10000
Where "-keystore testest.keystore" set's the name of your keystore file. 
"-alias test" is a max. 8 character alias to address the key, in this case it's called test
"-validity" set's the key-validity in days.
Remember your passwords and make sure you update your keystore file. If you lose any of it you can no longer update your game on google-play!
For google play: Your application must be signed with a cryptographic key whose validity period ends after 22 October 2033.
2. Sign the app, for example:
jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore test.keystore bin/hcraft1-release-unsigned.apk test -tsa http://timestamp.digicert.com
where "test" is the alias from above.
3. Align it:
zipalign -v 4 bin/hcraft1-release-unsigned.apk bin/hcraft1-release.apk
4. When putting it on google-play you must increase android:versionCode in AndroidManifest.xml each time.

Be careful - once you start uploading any files to google-play you should use your final keystore already.
Also for info... the first release on google-play took it's time (~2 days in my case). But the next release got faster (minutes to hours).

When distributing beta's to other people they have to enable:
On old Android: Settings→Applications-Unknown Sources
On new Android: Settings-Security-Unknown Sources

Debug .apk's can only be installed with adb to my knowledge.
