Release naming conventions
How to build from sources
How to make a release
How to build release packages
Naming conventions
Software revision follow the <major>.<minor>.<patch> scheme :
- the major number changes when major changes are included since the previous version,
- the minor number changes when important (but not major) changes are included since the previous version,
- the patch number changes when only bug fixes (no real new feature) have been completed since the previous version.
We may use "Alpha", "beta" and "release candidate" version (not always) ; in such cases, we use the following naming scheme :
- Alpha : <major>.<minor>.<patch>-a<alpha number> (example: "2.0.0-a1", "2.0.0-a2", ...),
- Beta : <major>.<minor>.<patch>-b<beta number> (example: "1.4.0-b1", ...),
- Release candidate : <major>.<minor>.<patch>-rc<release candidate number> (example: "1.4.0-rc1", ...).
Finally, as a last precaution, we may include the corresponding SVN revision in the version name, as in :
- the binary and source package files we releases (example: speed-dreams-1.4.0-r2307-win32-setup.exe),
- the in-game version indicators in the splash screen and in every menu help screen (ex: 2.0.0-a1-r2720)
In the SVN repository, we define 3 main folders in order to cope with releases :
- trunk : the root folder of source tree for the main stream developments
- branches : the folder where "branch" source trees are stored ;
- maintenance branches are the place where we fix bugs in officially released versions ; they are named "<major>.<minor>.x" (example: "branches/1.4.x"),
- development branches are the place where we develop new big things that would prevent the other developers from working on the trunk for the next release, or for which we don't know yet if we'll release them one day (experimental).
- tags : the folder where "tagged" source trees are stored ; tagged source trees are frozen snapshots (copies) of the trunk or some branch corresponding to officially released versions; the name of their root folder is simply the name of the version example: "tags/1.4.0", "tags/2.0.0-a1").
How to build from sources
See source:trunk/INSTALL.txt for the 2.x series, source:tags/1.4.0/INSTALL for the 1.4.0
Build times examples (trunk r3276)
| CPU | Disk | OS | Compiler | Build configuration | Parallel jobs | Elapsed time (mm:ss) |
| AMD 64 x 2 4600+ (2.4 GHz) DDR2 800 | Western Digital Raptor 74 Gb (10000 rpm, cache 8 Mb) | Linux Mandriva 2010.0 64 bits | GCC 4.4.1 | Debug, full contents | 1 | 02:11 |
| 2 | 01:09 | |||||
| Debug, Official contents | 1 | |||||
| 2 | ||||||
| Western Digital Caviar Black 500 Gb (7200 rpm, cache 32 Mb) | Windows XP SP2 32 bits | MSVC 2005 Pro | Debug, full contents | 1 | 03:18 | |
| 2 | 01:38 | |||||
| Intel Core2 Duo E8400 (3 GHz) DDR3 1066 | Hitashi Deskstar 160 Gb (7200 rpm, cache 8 Mb) | Windows XP SP2 32 bits | MSVC 2005 Pro | Debug, Official contents | 1 | 01:54 |
| 2 | 01:08 | |||||
| Intel Xeon 3250 (2.66 GHz) DDR3 1066 | Western Digital Caviar Blue 250 Gb (7200 rpm, cache 8 Mb) | Windows XP SP3 32 bits | MSVC 2005 Pro | Debug, Official contents | 2 | 01:04 |
| 4 | 01:00 | |||||
| 6 | 00:54 | |||||
| 8 | 00:50 |
How to make a release
Note:
- In below examples, we assume that we are freezing 'trunk' into 'tags/2.0.0-b1' for a 2.0.0 Beta 1 release.
- This applies only to the 2.x series (the 1.4 does is not built with CMake).
Linux
- update the release notes files (source:trunk/CHANGES.txt, source:trunk/doc/2.0.0.txt) : 'svn log' is your friend
- build your up-to-date trunk sandbox using the Release configuration
- test everything needed (no more detail about testing here, but very important and quite difficult to reach 100% coverage ...)
- freeze the source tree into a tag, inside the remote SVN server
svn copy https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/trunk@3935 https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/tags/2.0.0-b1 - checkout the tag or switch your trunk/branch sandbox to the tag
- alternative 1 : switch your trunk/branch sandbox to the tag (very quick, some seconds, few downloads)
cd mysandbox/trunk ./clobber.sh # if not there, cmake && make should generate it svn status -q # MANDATORY : make sure nothing is uncommitted ; fix it first if not ! rm CMakeLists.txt # will force SVN keyword substitution, to auto-generate the exact version name svn switch https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/tags/2.0.0-b1
- alternative 2 : checkout the tag (from far longer, as it downloads about 2 Gb)
cd mysandbox mkdir tags cd tags svn checkout https://speed-dreams.svn.sourceforge.net/svnroot/speed-dreams/tags/2.0.0-b1 2.0.0-b1 cd 2.0.0-b1
- alternative 1 : switch your trunk/branch sandbox to the tag (very quick, some seconds, few downloads)
- configure the build for the official contents and the Release (optimized) configuration (see above for more details, especially about external dependencies)
cmake -D OPTION_OFFICIAL_ONLY:BOOL=ON -D CMAKE_BUILT_TYPE:STRING=Release . # Note: Depending on your configuration, you migh also use '-D CMAKE_PREFIX_PATH:STRING=/usr/local'
- build and install
make sudo make install
- test the release (check cars, tracks, robots and modules-related contents ; check all race mode ; ...)
/usr/local/games/speed-dreams-2
- make the needed changes to the code / artwork in your 2.0.0-b1 sandbox
- loop back to 5 or 6 if any change was done
- commit any change to the tags (and don't forget to merge these back to the trunk later !)
Now, it's time for release package(s) ...
Windows
All the same as for Linux, but rather than the command line, you generally use graphical tools for dealing with SVN (ex: Tortoise SVN), compiling (MS Visual C++ 2005), ... etc ...
See the Windows chapter for more details about each build step in source:trunk/INSTALL.txt.
How to build release packages
If you didn't "make the release" yet, please do it, as explained above in "How to make a release".
Below, we assume you did it, and so that you enjoy a 2.0.0-b1 SVN sandbox where CMake was run at least once as explained above (step 5 : configure the build ...).
Source packages
These packages are the "reference" ones for any release, as all the binary packages can be rebuilt / must be "rebuildable" from them.
They contain only official contents (not the whole SVN repo. contents).
Linux
Alternative 1 (our preferred) : Multiple source packages
For official releases, we use the following multi-package scheme :
- base = game core sources and data + 1 1st class car set + 1 1st class track
- other official 1st class cars and tracks
- other official 1st class cars and tracks
- more official but lower quality / WIP / no AI - cars and tracks
- unmaintained contents (old physics engines)
The small base package is designed to become at the end a quick-download-and-try one, a kind of demo one.
But for the moment, you need to download and extract all of these source packages before starting to build (due to the limitations of our current CMake build system).
To build these packages, things are simple :
- cd to the top of your SVN source tree
- well, for the moment, not that simple : you have to hack the root CMakeLists.txt in order the in-game version name is generated correctly building outside of a SVN local copy, as it will be the case for the packages we are generating :
- run the packaging/sources/build.sh script, and give it the version of your packages
./packaging/sources/build.sh 2.0.0-b1-r3937
That's all : after some minutes, you've got all of the .tar.xz packages
To extract these packages :
mkdir sd-2.0.0-b1-r3937-src cd sd-2.0.0-b1-r3937-src for file in <packages folder>/*.xz; do tar xvfa $file; done
Alternative 2 : All-in-one source package
- automatically generate the full-contents source package (unfortunately, the (our?) CMake source packager does not do any filtering) (as a .tar.bz2 file)
make package_source
- extract it (we need to clean it up) :
tar xvfj speed-dreams-2.0.0-b1-r3937-src.tar.bz2
- cleanup the resulting source tree from unofficial contents
cd speed-dreams-2.0.0-b1-r3937-src # Docs you can find online rm -fr doc/tutorials # Race modes rm src/raceman/networkrace.xml rm src/raceman/championship-mpa1.xml # Robots rm -fr src/drivers/bt rm -fr src/drivers/networkhuman rm -fr src/drivers/hymie rm -fr src/drivers/K1999 rm -fr src/drivers/simplix/simplix_mpa1 # Tracks rm -fr data/tracks/development rm -fr data/tracks/dirt/dirt-5 rm -fr data/tracks/circuit/bueno rm -fr data/tracks/gprix rm -fr data/tracks/karting rm -fr data/tracks/road/Salty rm -fr data/tracks/road/longday # Cars rm -fr data/cars/models/gtc-aichi-aidoru rm -fr data/cars/models/ls1-cavallo-570s1 rm -fr data/cars/models/ls1-marisatech-gt4r rm -fr data/cars/models/lancer09-wr rm -fr data/cars/models/lp1-* rm -fr data/cars/models/lp2-* rm -fr data/cars/models/mp1* rm -fr data/cars/models/mp10-* rm -fr data/cars/models/mpa1* rm -fr data/cars/models/nascar-* rm -fr data/cars/models/ref-boxer-gt3-rs-2010 rm data/tracks/dirt/garguree/garguree.ac rm data/tracks/dirt/dirt-2/dirt-2.ac rm data/tracks/dirt/dirt-1/dirt-1.ac rm data/tracks/dirt/mixed-1/mixed-1.ac rm data/tracks/speedway/manton/manton.acc rm data/tracks/speedway/newton/newton.acc rm data/tracks/road/alpine-2/alpine-2.ac rm data/tracks/road/e-track-2/e-track-2.ac rm data/tracks/road/charmey/charmey.ac rm data/tracks/road/prenzlau/prenzlau.ac rm data/tracks/road/street-1/street-1.ac rm data/tracks/road/e-track-1/e-track-1.ac rm data/tracks/circuit/chemisay/chemisay.ac rm data/tracks/circuit/forza/forza.ac rm data/tracks/circuit/aalborg/aalborg.ac rm data/tracks/circuit/karwada/karwada.ac rm data/tracks/circuit/corkscrew/corkscrew.ac rm data/tracks/circuit/migrants/migrants.ac rm data/tracks/circuit/ruudskogen/ruudskogen.ac
4. archive and compress (lzma) the resulting source tree
cd .. tar -c -v -f - speed-dreams-2.0.0-b1-r3937-src | 7zr a -m0=lzma -mx=9 -mfb=64 -md=32m xxx.tar.7z speed-dreams-2.0.0-b1-r3937-src.tar.7z
That's all :-)
To extract this package under Linux :
7zr x -so speed-dreams-2.0.0-b1-r3937-src.tar.7z | tar xvf -
Under Windows, you can use the excellent 7-Zip.
Windows
We don't build source packages under Windows, but if it is needed, here's how to.
Alternative 1 (our preferred) : Multiple source packages
You can use the Linux method, after installing MSYS or CygWin? (gives your a Linux shell and tool set under Windows).
Alternative 2 : All-in-one source package
Basically, you'll use the same procedure as for Linux, but through different tools :
- to "automatically build the full-contents all-in-one source package" (as a ZIP archive), you'll use MS Visual Studio, and "build" the "PACKAGE_SRC" project,
- to "extract this full-contents all-in-one source package", you'll use any ZIP archiver (7-Zip is an excellent one),
- to "cleanup the resulting source tree from unofficial contents", you'll probably simply use your Windows explorer, but will surely remove the same file/folders,
- to "archive and compress (lzma) the resulting source tree", you'll use 7-Zip in order to get the best possible compression ratio. Note however that the resulting source package will not be a compressed "tarball" (a .tar.7z file), but a compressed tree (a .7z file) ... meaning that one will have to use a different command in order to extract it under Linux :
7zr x -so speed-dreams-2.0.0-b1-r3937-src.7z
Binary package(s)
Here's how to build packages that suit for direct and automatic installation on various OSes : the kind that the end-users prefer (and the developers don't like to make ;-).
Whatever the target OS, you start from the "all-in-one" source package, or from the SVN release tag ... as you like.
Let's assume that you've got such a source tree, already built it with "official contents only" and as a "Release" configuration (optimized compilation).
Windows
Multi-installers scheme
We use this one for official releases :
- multiple NSIS packages
- base = demo = game core binaries and data + 1 1st class car set + 1 1st class track
- other official 1st class cars and tracks
- other official 1st class cars and tracks
- more official but lower quality / WIP / no AI - cars and tracks
- the small base package is designed as a quick download and try one, a kind of demo one
- it also enables the user to download and install the other packages in a few simple clicks
After the "make a release" loop (build, install, test, change, loop until OK), you enter here a "make the packages" loop if it was not achieved earlier : at the end, you must be happy with your packages (official contents, the game works, ...).
Once OK about the contents of the packages, you have to tweak the last detail : the release name. As it is automatically built in the game binaries (splash screen, help screens, console log) and package file names from the actual SVN version of the tree, you have to commit your last changes (to the .nsi / .nsh files in the tags/2.0.0-b1/installer/windows folder) and generate the packages one last time.
Wait a minute : for the moment, this is not fully automatic, as you need to manually tweak the SVN revision in source:tags/2.0.0-b1/installer/windows/speed-dreams.nsh :
- look at the current revision, add 1 to it (you'll have to commit) and then set the "VER_REVISION" define (in the first lines of speed-dreams.nsh)
- then commit these changes to tags/2.0.0-b1
- remove the top CMakeLists.txt
- svn update to get it back, but with updated SVN keywords inside, useful for you to get the right SVN revision in the splash screen, help screens, console log
Then, you'll be done after :
- a full rebuild and install, as explained above in "make the release"
- generating all of the multiple NSIS packages (through NSIS's "compile NSI script" tool)
- a last test of these package in order to see if all's right (especially the SVN revision number ;-)
All-in-one (monolithic) NSIS binary package
We don't use it, for now, but in case it is useful to anyone, it is simple and automatically generates an executable package suitable for Windows XP, Vista and 7.
Simply build the "PACKAGE" project with MS Visual Studio.
Note: You can get different binary packages : run cmake GUI and check the PACKAGERS_BINARY variables.
Linux
Our CMake build system has some support for building Linux binary packages, based on what is configured to be built and installed (see above cmake command line options, especially the "official-only" stuff).
You can get different binary packages : run ccmake and check the PACKAGERS_BINARY variables.
To build the chosen package :
make package
Note: In order to get .deb binary packages for other platforms than Ubuntu 9.10, you'll need to change source:trunk/cmake/packagemaker.cmake
TO BE COMPLETED for each distro. ... volunteers are welcome :-)
==== Ubuntu ===
To be completed, made more step-by-step precise.
- build the targeted release, as explain above,
- 'make package' for a Ubuntu 9.10 .deb binary package.
...
Fedora
...
Mandriva
...
