From a53ec7fb12a4ac307c5c3ca3ebcd6a5ff4fe16d3 Mon Sep 17 00:00:00 2001 From: Alice Date: Tue, 1 May 2018 12:50:28 -0700 Subject: [PATCH] refactor(docs): Fix grammer and wording in the cross-compile guide Rewrote the cross-compile guide to make it easier to understand. --- windows/cross-compile/README.md | 126 ++++++++++++++++---------------- 1 file changed, 65 insertions(+), 61 deletions(-) diff --git a/windows/cross-compile/README.md b/windows/cross-compile/README.md index 4ab865089..7ed64ab02 100644 --- a/windows/cross-compile/README.md +++ b/windows/cross-compile/README.md @@ -1,85 +1,96 @@ -# Cross-compile from Linux +# Cross-compile from Linux to Windows ## Intro -Following these instructions you will be able to cross-compile qTox to Windows. +Following these instructions will show you how to cross-compile qTox for Windows. -This script can be used by qTox power users to cross-compile qTox themselves,as - well as by qTox developers to make sure their local changes don't break -cross-compilation to Windows. +This script can be used by qTox users and devs to compile qTox for windows themselves. -Note that the compilation script doesn't build the updater and doesn't produce +Please note that the compilation script doesn't build the updater and doesn't produce an installer. ## Usage -[Install Docker](https://docs.docker.com/engine/installation/linux/). -You should have 3 directories available (names don't have to match the given -ones): +#### 1. [Install Docker](https://docs.docker.com/install). +*** -1. `workspace` -- a directory that will contain a cache of qTox dependencies -and the final qTox cross-compilation build. You should create this directory. -2. `script` -- a directory that contains the `build.sh` script. You can use -this directory for this, there is no need to create a new one. -3. `qtox` -- a root directory of a qTox repository. This directory contains -qTox source code that will be cross-compiled. You can use the root of this qTox -repository, there is no need to create a new one. -These directories will be mounted inside a Docker container at `/workspace`, -`/script` and `/qtox`. +#### 2. Create 3 directories for storing the files needed for cross-compiling. +*** -The contents of `qtox` and `script` directories wouldn't be modified. The -`build.sh` script actually makes a copy of `qtox` directory and works on that -copy. + * `workspace` -- a directory that will contain a cache of qTox dependencies + and the final qTox cross-compilation build. You should create this directory. -Once you sort out the directories, you are ready to run the `build.sh` script -in a Docker container. + * `script` -- a directory that contains the `build.sh` script. + Copy the `build.sh` script to this folder. + + * `qtox` -- the root directory of a qTox repository. This directory must contain + the qTox source code that will be cross-compiled. You can use an existing qTox + directory you've been using for development or check one out using + `git clone https://github.com/qTox/qTox.git folder-name` + +These directories will be mounted inside a Docker container at`/workspace`, +`/script`and`/qtox`. + +The contents of `qtox` and `script` directories are not modified during compilation. The +`build.sh` script makes a temporary copy of the `qtox` directory for compilation. + + +#### 3. Create the docker container and run the build script. +*** +> Note that the`build.sh`script takes 2 arguments: architecture and build type. +> Valid values for the architecture are `i686` for 32-bit and `x86_64` for +> 64-bit. Valid values for the build type are `release` and `debug`. All case +> sensitive. You can modify the scripts below to fit your use case. +> To create the docker container and start cross-compiling run -Note that the `build.sh` script takes 2 arguments: architecture and build type. -Valid values for the architecture are `i686` for 32-bit and `x86_64` for -64-bit. Valid values for the build type are `release` and `debug`. All case -sensitive. -Now, to start the cross-compilation, for example, for a 32-bit release qTox, run ```sh sudo docker run --rm \ - -v /absolute/path/to/your/workspace:/workspace \ - -v /absolute/path/to/your/script:/script \ - -v /absolute/path/to/your/qtox:/qtox \ - debian:stretch-slim \ - /bin/bash /script/build.sh i686 release +-v /absolute/path/to/your/workspace:/workspace \ +-v /absolute/path/to/your/script:/script \ +-v /absolute/path/to/your/qtox:/qtox \ +debian:stretch-slim \ +/bin/bash /script/build.sh i686 release ``` -If you are a qTox developer, you might want to instead run + +If you are a qTox developer, you might want to enable tty and leave stdin open by running the following script instead. ```sh -# Get shell inside Debian Stretch container so that you can poke around if needed sudo docker run -it \ - --rm \ - -v /absolute/path/to/your/workspace:/workspace \ - -v /absolute/path/to/your/script:/script \ - -v /absolute/path/to/your/qtox:/qtox \ - debian:stretch-slim \ - /bin/bash -# Run the script -bash /script/build.sh i686 release +--rm \ +-v /absolute/path/to/your/workspace:/workspace \ +-v /absolute/path/to/your/script:/script \ +-v /absolute/path/to/your/qtox:/qtox \ +debian:stretch-slim \ +/bin/bash /script/build.sh i686 release ``` - -This will cross-compile all of the qTox dependencies and qTox itself, storing +These will cross-compile all of the qTox dependencies and qTox itself, storing them in the `workspace` directory. The first time you run it for each architecture, it will take a long time for the cross-compilation to finish, as -qTox has a lot of dependencies that need to be cross-compiled. It takes my -Intel Core i7 processor about 125 minutes for the cross-compilation to get done -on a single core, and about 30 minutes using all 8 hyperthreads. But once you -do it once for each architecture, the dependencies will get cached inside the -`workspace` directory, and the next time you build qTox, the `build.sh` script -will skip recompiling them, going straight to compiling qTox, which is a lot -faster -- about 8 minutes on a single core and 2 minutes using 8 hyperthreads. +qTox has a lot of dependencies that need to be cross-compiled. -The structure of `workspace` directory that the `build.sh` script will create -is as follows: + +> Note that it takes my Intel Core i7 processor about 125 minutes on average for the cross-compilation +> to finish on a single core, and about 30 minutes using all 8 hyperthreads. Once you've compiled +> it, the dependencies will be cached inside the `workspace` directory. The next time +> you build qTox, the `build.sh` script will skip recompiling them +> which is a lot faster -- about 8 minutes on a single core and 2 minutes using 8 hyperthreads. + + +#### 4. After cross-compiling has finished +*** +The `workspace\i686\qtox` and `workspace\x86_64\qtox\`directories will contain the compiled binaries in their respective debug or release folder depending on the compilation settings you chose in Step 3. + +The `dep-cache` directory is where all the cross-compiled qTox dependencies will be +cached for the future builds. You can remove any directory inside the `deps` folder, which +will result in the `build.sh` re-compiling the removed dependency. + + +_The `workspace` direcory structure for reference_ ``` workspace @@ -116,10 +127,3 @@ workspace ├── debug └── release ``` - -The `dep-cache` directory is where all cross-compiled qTox dependencies will be -cached for the future runs. You can remove any directory inside `deps`, which -will result in the `build.sh` re-compiling the missing dependency. - -The `qtox` directory, split into `debug` and `release`, is where the -cross-compiled qTox will be stored.