Move style_guide.md and building.md to docs/

2 files changed, 142 insertions, 0 deletions

diff --git a/docs/building.md b/docs/building.md
new file mode 100644
index 000000000..860efab35
--- /dev/null
+++ b/docs/building.md
@@ -0,0 +1,58 @@
+# Building
+
+You must have a 64-bit machine for building and running the project. Always
+run your system updater before building and make sure you have the latest
+video drivers for your card.
+
+## Setup
+
+### Windows
+
+* Windows 8 or 8.1
+* Visual Studio 2015
+* [Python 2.7](http://www.python.org/download/releases/2.7.6/)
+* If you are on Windows 8, you will also need the [Windows 8.1 SDK](http://msdn.microsoft.com/en-us/windows/desktop/bg162891)
+
+Ensure Python is in your PATH (`C:\Python27\`).
+
+I recommend using [Cmder](http://cmder.net/) for git and command
+line usage.
+
+#### Debugging
+
+VS behaves oddly with the debug paths. Open the xenia project properties
+and set the 'Command' to `$(SolutionDir)$(TargetPath)` and the
+'Working Directory' to `$(SolutionDir)..\..`. You can specify flags and
+the file to run in the 'Command Arguments' field (or use `--flagfile=flags.txt`).
+
+By default logs are written to a file with the name of the executable. You can
+override this with `--log_file=log.txt`.
+
+If running under Visual Studio and you want to look at the JIT'ed code
+(available around 0xA0000000) you should pass `--emit_source_annotations` to
+get helpful spacers/movs in the disassembly.
+
+### Linux
+
+Linux support is extremely experimental and presently incomplete.
+
+The build script uses LLVM/Clang 3.8. GCC should also work, but is not easily
+swappable right now.
+
+[CodeLite](http://codelite.org) is the IDE of choice and `xb premake` will spit
+out files for that. Make also works via `xb build`.
+
+To get the latest Clang on an ubuntu system:
+
+```
+sudo -E apt-add-repository -y "ppa:ubuntu-toolchain-r/test"
+curl -sSL "http://llvm.org/apt/llvm-snapshot.gpg.key" | sudo -E apt-key add -
+echo "deb http://llvm.org/apt/precise/ llvm-toolchain-precise main" | sudo tee -a /etc/apt/sources.list > /dev/null
+sudo -E apt-get -yq update &>> ~/apt-get-update.log
+sudo -E apt-get -yq --no-install-suggests --no-install-recommends --force-yes install clang-3.8 clang-format-3.8
+```
+
+## Running
+
+To make life easier you can use `--flagfile=myflags.txt` to specify all
+arguments, including using `--target=my.xex` to pick an executable.
diff --git a/docs/style_guide.md b/docs/style_guide.md
new file mode 100644
index 000000000..c1789af5d
--- /dev/null
+++ b/docs/style_guide.md
@@ -0,0 +1,84 @@
+# Style Guide
+
+The style guide can be summed up as 'clang-format with the Google style set'.
+In addition, the [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml)
+is followed and cpplint is the source of truth. When in doubt, defer to what
+code in the project already does.
+
+Base rules:
+
+* 80 column line length max
+* LF (Unix-style) line endings
+* 2-space soft tabs, no TABs!
+* [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) for naming/casing/etc
+* Sort includes according to the [style guide rules](http://google-styleguide.googlecode.com/svn/trunk/cppguide.html#Names_and_Order_of_Includes)
+* Comments are properly punctuated (that means capitalization and periods, etc)
+* TODO's must be attributed like `// TODO(yourgithubname): foo.`
+
+Code that really breaks from the formatting rules will not be accepted, as then
+no one else can use clang-format on the code without also touching all your
+lines.
+
+### Why?
+
+To quote the [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml):
+
+```
+One way in which we keep the code base manageable is by enforcing consistency.
+It is very important that any programmer be able to look at another's code and
+quickly understand it. Maintaining a uniform style and following conventions
+means that we can more easily use "pattern-matching" to infer what various
+symbols are and what invariants are true about them. Creating common, required
+idioms and patterns makes code much easier to understand. In some cases there
+might be good arguments for changing certain style rules, but we nonetheless
+keep things as they are in order to preserve consistency.
+```
+
+## Buildbot Verification
+
+The buildbot runs `xb lint --all` on the master branch, and will run
+`xb lint --origin` on pull requests. Run `xb format` before you commit each
+local change so that you are consistently clean, otherwise you may have to
+rebase. If you forget, run `xb format --origin` and rebase your changes (so you
+don't end up with 5 changes and then a 6th 'whoops' one - that's nasty).
+
+The buildbot is running LLVM 3.8.0. If you are noticing style differences
+between your local lint/format and the buildbot, ensure you are running that
+version.
+
+## Tools
+
+### clang-format
+
+clang-format with the Google style is used to format all files. I recommend
+installing/wiring it up to your editor of choice so that you don't even have to
+think about tabs and wrapping and such.
+
+#### Command Line
+
+To use the `xb format` auto-formatter, you need to have a `clang-format` on your
+PATH. If you're on Windows you can do this by installing an LLVM binary package
+from [the LLVM downloads page](http://llvm.org/releases/download.html). If you
+install it to the default location the `xb format` command will find it
+automatically even if you don't choose to put all of LLVM onto your PATH.
+
+#### Visual Studio
+
+Grab the official [experimental Visual Studio plugin](http://llvm.org/builds/).
+To switch to the Google style go Tools -> Options -> LLVM/Clang -> ClangFormat
+and set Style to Google. Then use ctrl-r/ctrl-f to trigger the formatting.
+Unfortunately it only does the cursor by default, so you'll have to select the
+whole doc and invoke it to get it all done.
+
+If you have a better option, let me know!
+
+#### Xcode
+
+Install [Alcatraz](http://alcatraz.io/) to get the [ClangFormat](https://github.com/travisjeffery/ClangFormat-Xcode)
+package. Set it to use the Google style and format on save. Never think about
+tabs or linefeeds or whatever again.
+
+### cpplint
+
+TODO(benvanik): write a cool script to do this/editor plugins.
+In the future, the linter will run as a git commit hook and on travis.