From fcfa9b6060789017566d2ed2195ca5bf37b7f973 Mon Sep 17 00:00:00 2001 From: Matt McCormick Date: Mon, 16 Apr 2018 15:40:01 -0400 Subject: [PATCH] README: Improve section order New users should see the most relevant sections first. In particular, - Examples - Installation - Usage --- README.rst | 133 ++++++++++++++++++++++++++--------------------------- 1 file changed, 66 insertions(+), 67 deletions(-) diff --git a/README.rst b/README.rst index 1f574fb..025a64d 100644 --- a/README.rst +++ b/README.rst @@ -12,6 +12,7 @@ Features * Pre-built and configured toolchains for cross compiling. * Most images also contain an emulator for the target system. +* Clean separation of build tools, source code, and build artifacts. * Commands in the container are run as the calling user, so that any created files have the expected ownership, (i.e. not root). * Make variables (`CC`, `LD` etc) are set to point to the appropriate tools in the container. * Recent `CMake `_ and ninja are precompiled. @@ -20,15 +21,61 @@ Features * Current directory is mounted as the container's workdir, ``/work``. * Works with the `Docker for Mac `_ and `Docker for Windows `_. +Examples +-------- -What is the difference between `dockcross` and `dockbuild` ? ------------------------------------------------------------- +1. ``dockcross make``: Build the *Makefile* in the current directory. +2. ``dockcross cmake -Bbuild -H. -GNinja``: Run CMake with a build directory + ``./build`` for a *CMakeLists.txt* file in the current directory and generate + ``ninja`` build configuration files. +3. ``dockcross ninja -Cbuild``: Run ninja in the ``./build`` directory. +4. ``dockcross bash -c '$CC test/C/hello.c -o hello'``: Build the *hello.c* file + with the compiler identified with the ``CC`` environmental variable in the + build environment. +5. ``dockcross bash``: Run an interactive shell in the build environment. -The key difference is that `dockbuild `_ -images use the same method to conveniently isolate the build environment as -`dockcross `_ but they do **NOT** provide -a toolchain file. +Note that commands are executed verbatim. If any shell processing for +environment variable expansion or redirection is required, please use +`bash -c 'command args...'`. +Installation +------------ + +This image does not need to be run manually. Instead, there is a helper script +to execute build commands on source code existing on the local host filesystem. This +script is bundled with the image. + +To install the helper script, run one of the images with no arguments, and +redirect the output to a file:: + + docker run --rm CROSS_COMPILER_IMAGE_NAME > ./dockcross + chmod +x ./dockcross + mv ./dockcross ~/bin/ + +Where `CROSS_COMPILER_IMAGE_NAME` is the name of the cross-compiler toolchain +Docker instance, e.g. `dockcross/linux-armv7`. + +Only 64-bit x86_64 images are provided; a 64-bit x86_64 host system is required. + +Usage +----- + +For the impatient, here's how to compile a hello world for armv7:: + + cd ~/src/dockcross + docker run --rm dockcross/linux-armv7 > ./dockcross-linux-armv7 + chmod +x ./dockcross-linux-armv7 + ./dockcross-linux-armv7 bash -c '$CC test/C/hello.c -o hello_arm' + +Note how invoking any toolchain command (make, gcc, etc.) is just a matter of prepending the **dockcross** script on the commandline:: + + ./dockcross-linux-armv7 [command] [args...] + +The dockcross script will execute the given command-line inside the container, +along with all arguments passed after the command. Commands that evaluate +environmental variables in the image, like `$CC` above, should be executed in +`bash -c`. The present working directory is mounted within the image, which +can be used to make source code available in the Docker container. Cross compilers --------------- @@ -164,44 +211,13 @@ dockcross/windows-x86 |windows-x86-images| 32-bit Windows cross-compiler based on MXE/MinGW-w64. -Installation ------------- +Articles +-------- -This image does not need to be run manually. Instead, there is a helper script -to execute build commands on source code existing on the local host filesystem. This -script is bundled with the image. - -To install the helper script, run one of the images with no arguments, and -redirect the output to a file:: - - docker run --rm CROSS_COMPILER_IMAGE_NAME > ./dockcross - chmod +x ./dockcross - mv ./dockcross ~/bin/ - -Where `CROSS_COMPILER_IMAGE_NAME` is the name of the cross-compiler toolchain -Docker instance, e.g. `dockcross/linux-armv7`. - -Only 64-bit images are provided; a 64-bit host system is required. - -Usage ------ - -For the impatient, here's how to compile a hello world for armv7:: - - cd ~/src/dockcross - docker run --rm dockcross/linux-armv7 > ./dockcross-linux-armv7 - chmod +x ./dockcross-linux-armv7 - ./dockcross-linux-armv7 bash -c '$CC test/C/hello.c -o hello_arm' - -Note how invoking any toolchain command (make, gcc, etc.) is just a matter of prepending the **dockcross** script on the commandline:: - - ./dockcross-linux-armv7 [command] [args...] - -The dockcross script will execute the given command-line inside the container, -along with all arguments passed after the command. Commands that evaluate -environmental variables in the image, like `$CC` above, should be executed in -`bash -c`. The present working directory is mounted within the image, which -can be used to make source code available in the Docker container. +- `dockcross: C++ Write Once, Run Anywhere + `_ +- `Cross-compiling binaries for multiple architectures with Docker + `_ Built-in update commands @@ -285,23 +301,6 @@ For example, commands like ``git config --global advice.detachedHead false`` can be added to this script. -Examples --------- - -1. ``dockcross make``: Build the *Makefile* in the current directory. -2. ``dockcross cmake -Bbuild -H. -GNinja``: Run CMake with a build directory - ``./build`` for a *CMakeLists.txt* file in the current directory and generate - ``ninja`` build configuration files. -3. ``dockcross ninja -Cbuild``: Run ninja in the ``./build`` directory. -4. ``dockcross bash -c '$CC test/C/hello.c -o hello'``: Build the *hello.c* file - with the compiler identified with the ``CC`` environmental variable in the - build environment. -5. ``dockcross bash``: Run an interactive shell in the build environment. - -Note that commands are executed verbatim. If any shell processing for -environment variable expansion or redirection is required, please use -`bash -c 'command args...'`. - How to extend Dockcross images ------------------------------ In order to extend Dockcross images with your own commands, one must: @@ -312,7 +311,7 @@ In order to extend Dockcross images with your own commands, one must: An example Dockerfile would be:: FROM dockcross/linux-armv7 - + ENV DEFAULT_DOCKCROSS_IMAGE my_cool_image RUN apt-get install nano @@ -324,13 +323,13 @@ And then in the shell:: ./linux-armv7 bash # Runs the helper script with the argument "bash", which starts an interactive container using your extended image. -Articles --------- +What is the difference between `dockcross` and `dockbuild` ? +------------------------------------------------------------ -- `dockcross: C++ Write Once, Run Anywhere - `_ -- `Cross-compiling binaries for multiple architectures with Docker - `_ +The key difference is that `dockbuild `_ +images use the same method to conveniently isolate the build environment as +`dockcross `_ but they do **NOT** provide +a toolchain file. ---