diff options
| -rw-r--r-- | COMPILING.md | 79 | ||||
| -rw-r--r-- | CONTRIBUTING.md | 26 | ||||
| -rw-r--r-- | CONTRIBUTORS | 3 |
3 files changed, 65 insertions, 43 deletions
diff --git a/COMPILING.md b/COMPILING.md index fcd0e4826..1fd9ca8b4 100644 --- a/COMPILING.md +++ b/COMPILING.md @@ -1,30 +1,43 @@ -# COMPILING # +COMPILING +========= -To compile Cuberite from source, you need CMake and make, as well as a C compiler, C++ compiler and linker. To contribute code, you also need a Git client. +To compile Cuberite from source, you need the following set of software: -## Windows ## + * CMake + * Platform-specific make tool (windows would be MSVC, linux/osx GNU make, etc.) + * C compiler + * modern C++ compiler and linker + + To contribute code, you also need a Git client. + +Windows +------- + +We use Microsoft Visual Studio for Windows compilation. It is possible to use other toolchains, but we don't test against them and they aren't supported. Visual Studio 2013 Express for Desktop is being actively used for development. -We use Microsoft Visual Studio for Windows compilation. It is possible to use other toolchains, but it isn't tested nor supported. Visual Studio versions 2013 Express for Desktop is being actively used for development. You can find download links for VS2013 Express here: http://go.microsoft.com/?linkid=9832280 Next, you need to download and install CMake. Download from here: http://cmake.org/cmake/resources/software.html . You should download a full installation package, so that the installer will set everything up for you (especially the paths). -To contribute your changes to the sources back to the repository, you need a Git client. Options are: -- MsysGit: http://msysgit.github.io/ -- GitHub windows client: http://windows.github.com/ -- TortoiseGit: http://code.google.com/p/tortoisegit/ +To contribute your changes to the source back to the repository, you need a Git client. Options are: + + * MsysGit: http://msysgit.github.io/ + * GitHub windows client: http://windows.github.com/ + * TortoiseGit: http://code.google.com/p/tortoisegit/ + +Alternatively, if you want only to compile the source, without contributing, you can [download the sources in a ZIP file directly from GitHub](https://github.com/cuberite/cuberite/archive/master.zip). + +If you're using Git to get the source, use the following set of commands to set up the local workspace correctly: -Alternatively, if you want only to compile the source, without contributing, you can download the sources in a ZIP file directly from GitHub: https://github.com/cuberite/cuberite/archive/master.zip -If you're using Git to get the sources, use the following set of commands to set up the local workspace correctly: ``` git clone --recursive https://github.com/cuberite/cuberite.git ``` -Now that you have the sources, it's time to prepare the project files for your favorite compiler. Open a command window in the folder with the sources and type in `cmake .` . This will run CMake, it will auto-detect your Visual Studio version and produce the appropriate project and solution files. +Now that you have the source, it's time to prepare the project files for your favorite compiler. Open a command window in the folder with the source and type in `cmake .` . This will run CMake, it will auto-detect your Visual Studio version and produce the appropriate project and solution files. Finally, open the newly created file, `Cuberite.sln`, in your Visual Studio. -If you want to run Cuberite from within the IDE, you need to first make sure that it will be run with the correct home folder. Normally this happens automatically, but for some Visual Studio versions the process doesn't stick. Right-click on the Cuberite project in the Solution Explorer tool window, and select Properties. In the dialog, navigate to Configuration properties -> Debugging in the tree on the left, then make sure the value `Working Directory` is set to `../Server`. If you don't do this, the server won't be able to find crafting recipes, item names or plugins. +If you want to run Cuberite from within VS, you need to first make sure that it will be run with the correct home folder. Normally this happens automatically, but for some Visual Studio versions the process doesn't stick. Right-click on the Cuberite project in the Solution Explorer tool window, and select Properties. In the dialog, navigate to Configuration properties -> Debugging in the tree on the left, then make sure the value `Working Directory` is set to `../Server`. If you don't do this, the server won't be able to find crafting recipes, item names or plugins. ### Release configuration ### @@ -32,16 +45,19 @@ To make Visual Studio produce the version with the best performance, you will ne ### Debug configuration ### -In order to tinker with the code, you'll more than likely need to use the debugging features of the IDE. To make them the easiest to use, you should switch to the Debug configuration - this provides the highest level of information while debugging, for the price of the executable being 2 - 10 times slower. Go to menu Build -> Configuration Manager, and in the opened dialog, change the top left combo box (Active solution configuration) to Debug. Close the dialog and build the solution. The resulting executable is called `Cuberite_debug.exe` in the `Server` folder. +In order to tinker with the code, you'll more than likely need to use the debugging features of your IDE. To make them the easiest to use, you should switch to the Debug configuration - this provides the highest level of information while debugging, for the price of the executable being 2 - 10 times slower. Go to menu Build -> Configuration Manager, and in the opened dialog, change the top left combo box (Active solution configuration) to Debug. Close the dialog and build the solution. The resulting executable is called `Cuberite_debug.exe` in the `Server` folder. + +OSX +--- -## OSX ## Install git from its [website](http://git-scm.com) or homebrew: `brew install git`. -Install Xcode (commandline tools are recommended) from the App Store or https://developer.apple.com/downloads. +Install Xcode (commandline tools are recommended) from the App Store or [the website](https://developer.apple.com/downloads). Install CMake from its [website](http://cmake.org) or homebrew: `brew install cmake`. ### Getting the sources ### + ``` git clone --recursive https://github.com/cuberite/cuberite.git ``` @@ -53,15 +69,18 @@ Follow the instructions at [CMake on Unix-based platforms](#cmake-on-unix-based- After doing so, run the command `xcodebuild lib/polarssl/POLARSSL.xcodeproj` in the build directory, in order to build polarssl, a library that is required by Cuberite. Lastly, run the command `xcodebuild` to build Cuberite. Optionally, you may open the project files for polarssl and then Cuberite in Xcode and build there. -## Linux, FreeBSD etc. ## +Linux, FreeBSD etc. +------------------- + +Install git, make, cmake and clang (or gcc), using your platform's package manager. debian/ubuntu: -Install git, make, cmake and gcc or clang, using your platform's package manager: ``` -sudo apt-get install git make cmake gcc g++ +sudo apt-get install git make cmake clang ``` -(Ensure you have gcc/g++ 4.8 or higher installed to avoid errors during compilation) +(Ensure you have a recent version of clang, or gcc/g++ 4.8 or higher installed to avoid errors during compilation) + +### Getting the source ### -### Getting the sources ### ``` git clone --recursive https://github.com/cuberite/cuberite.git ``` @@ -70,21 +89,24 @@ git clone --recursive https://github.com/cuberite/cuberite.git Follow the instructions at [CMake on Unix-based platforms](#cmake-on-unix-based-platforms). -After doing so, run the command `make` in the build directory, and Cuberite will build. +After doing so, run the command `make` in the build directory, and Cuberite will build. -## CMake on Unix-based platforms ### +CMake on Unix-based platforms +----------------------------- ### Release Mode ### Release mode is preferred for almost all cases, it has much better speed and less console spam. However, if you are developing Cuberite actively, debug mode might be better. Assuming you are in the Cuberite folder created in the initial setup step, you need to run these commands: + ``` mkdir Release cd Release cmake -DCMAKE_BUILD_TYPE=RELEASE .. ``` -NOTE: CMake can generate project files for many different programs, such as Xcode, eclipse, and ninja. To use a different generator, first type `cmake --help`, and at the end, cmake will output the different generators that are available. To specify one, add `-G` followed by the name of the generator, in the `cmake` command. Note that the name is case-sensitive. + +NOTE: CMake can generate project files for many different programs, such as Xcode, eclipse, and ninja. To use a different generator, first type `cmake --help`, and at the end, cmake will output the different generators that are available. To specify one, add `-G` followed by the name of the generator, in the `cmake` command. Note that the name is case-sensitive. The executable will be built in the `cuberite/Server` folder and will be named `Cuberite`. @@ -93,30 +115,31 @@ The executable will be built in the `cuberite/Server` folder and will be named ` Debug mode is useful if you want more debugging information about Cuberite while it's running or if you want to use a debugger like GDB to debug issues and crashes. Assuming you are in the Cuberite folder created in the Getting the sources step, you need to run these commands: + ``` mkdir Debug cd Debug cmake -DCMAKE_BUILD_TYPE=DEBUG .. ``` -NOTE: CMake can generate project files for many different programs, such as Xcode, eclipse, and ninja. To use a different generator, first type `cmake --help`, and at the end, cmake will output the different generators that are available. To specify one, add `-G` followed by the name of the generator, in the `cmake` command. Note that the name is case-sensitive. + +NOTE: CMake can generate project files for many different programs, such as Xcode, eclipse, and ninja. To use a different generator, first type `cmake --help`, and at the end, cmake will output the different generators that are available. To specify one, add `-G` followed by the name of the generator, in the `cmake` command. Note that the name is case-sensitive. The executable will be built in the `cuberite/Server` folder and will be named `Cuberite_debug`. - + ### 32 Bit Mode switch ### This is useful if you want to compile Cuberite on an x64 (64-bit Intel) machine but want to use on an x86 (32-bit Intel) machine. This switch can be used with debug or release mode. Simply add: -DFORCE_32=1 - + to your cmake command and 32 bit will be forced. ### Compiling for another computer ### - When cross-compiling for another computer it is important to set cross compiling mode. This tells the compiler not to optimise for your machine. This switch can be used with debug or release mode. To enable, simply add: -DCROSSCOMPILE=1 to your cmake command. -Note that cross-compilation is probably broken at this moment, since the build requires running an executable that it has built, as part of the build process. +Note that real cross-compilation is hard at this moment, because an executable generated during the build process is required for later stages, so if your computer cannot run executables it generates the build will not work. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 592e331fa..ebe43f58b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,16 @@ Code Conventions ----------- +---------------- -When contributing, you must follow our code conventions. Otherwise, the CI builds will automatically fail and your PR will not be merged until the non-conforming code is fixed. Due to this, we strongly advise you to run `src/CheckBasicStyle.lua` before commiting, it will perform various code style checks and warn you if your code does not conform to our conventions. `CheckBasicStyle.lua` can be configured to run automatically before every commit via a pre-commit hook, **this is highly recommended**. The way to do it is listed at the bottom of this file. +When contributing, you must follow our code conventions. Otherwise, CI builds will automatically fail and your PR will not be merged until the non-conforming code is fixed. Due to this, we strongly advise you to run `src/CheckBasicStyle.lua` before committing, it will perform various code style checks and warn you if your code does not conform to our conventions. `CheckBasicStyle.lua` can be configured to run automatically before every commit via a pre-commit hook, **this is highly recommended**. There are instructions on how to achieve this at the bottom of this file. Here are the conventions: - * We use the subset of C++11 supported by MSVC 2013 (ask if you think that something would be useful) + * We use the subset of C++11 supported by MSVC 2013 (ask if you think that something outside of this subset would be useful) * All new public functions in all classes need documenting comments on what they do and what behavior they follow, use doxy-comments formatted as `/** Description */`. Do not use asterisks on additional lines in multi-line comments. * Use spaces after the comment markers: `// Comment` instead of `//Comment`. A comment must be prefixed with two spaces if it's on the same line with code: - `SomeFunction()<Space><Space>//<Space>Note the two spaces prefixed to me and the space after the slashes.` * All variable names and function names use CamelCase style, with the exception of single letter variables. - - `ThisIsAProperFunction()` `This_is_bad()` `this_is_bad` `GoodVariableName` `badVariableName`. + - `ThisIsAProperFunction()` `This_is_bad()` `this_is_bad()` `GoodVariableName` `badVariableName`. * All member variables start with `m_`, all function parameters start with `a_`, all class names start with `c`. - `class cMonster { int m_Health; int DecreaseHealth(int a_Amount); }` * Put spaces after commas. `Vector3d(1, 2, 3)` instead of `Vector3d(1,2,3)` @@ -37,17 +37,17 @@ Here are the conventions: * Alpha-sort stuff that makes sense alpha-sorting - long lists of similar items etc. * White space is free, so use it freely - "freely" as in "plentifully", not "arbitrarily" - * All `case` statements inside a `switch` need an extra indent. - * Each and every control statement deserves its braces. This helps maintainability later on when the file is edited, lines added or removed - the control logic doesn't break so easily. - - The only exception: a `switch` statement with all `case` statements being a single short statement is allowed to use the short brace-less form. + * All `case` statements inside a `switch` need an extra indent + * Each and every control statement deserves its braces. This helps maintainability later on when the file is edited, lines added or removed - the control logic doesn't break so easily + - The only exception: a `switch` statement with all `case` statements being a single short statement is allowed to use the short brace-less form - These two rules really mean that indent is governed by braces - * Add an empty last line in all source files (GCC and GIT can complain otherwise) + * Add an empty last line in all source files (GCC and Git can complain otherwise) Pre-commit hook --------- When contributing, the code conventions above *must* be followed. Otherwise, the CI builds will automatically fail and your PR will not be merged until the non-conforming code is fixed. It is highly recommended to set up a pre-commit hook which will check your code style before every commit. Here is how to do that: - * Clone the repository as usual. + * Clone the repository as usual. * Go to your `<clone location>/.git/hooks` folder, create a text file named "pre-commit" there with the following contents: ``` #!/bin/sh @@ -56,14 +56,12 @@ src/CheckBasicStyle.lua 1>&2 -g * If on Linux/Unix, you need to give the newly created file an execute permission: `chmod +x .git/hooks/pre-commit` * Lua must be installed. * You're done. Now, `src/CheckBasicStyle.lua` will check the changed files before every commit. If a problem is found, it will point you to that problem and will cancel the commit. - + Note that the check script is not smart enough to catch everything, so not having any warnings does not necessarily imply that you followed the conventions fully. The other humans working on this will perform more checks before merging. Copyright --------- -Your work must be licensed at least under the Apache license. - -You can add yourself to the CONTRIBUTORS file if you wish. +Your must either place your work in the public domain or licensed it under the Apache License 2.0, and if so you must add yourself to the contributors file to show that you accept the publication of your work under the license. -**PLUGINS ONLY**: If your plugin is not licensed under the Apache license, then it must be compatible and marked as such. This is only valid for the plugins included within the MCServer source; plugins developed on separate repositories can use whatever license they want. +**PLUGINS ONLY**: If your plugin is not licensed under the Apache license, then it must be compatible and marked as such. This is only valid for the plugins included within the Cuberite source; plugins developed on separate repositories can use whatever license they want. diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 4fbd3b7fd..87e5e9492 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -47,4 +47,5 @@ worktycho xoft (Mattes Dolak/madmaxoft on GH) Yeeeeezus (Donated AlchemistVillage prefabs) -Please add yourself to this list if you contribute to Cuberite. +Please add yourself to this list if you contribute to the official Cuberite project +and license your work under the Apache License 2.0 |