mirror of
https://github.com/bensuperpc/dockcross.git
synced 2024-11-10 05:07:26 +01:00
Merge pull request #219 from thewtex/readme-order
README: Improve section order
This commit is contained in:
Matt McCormick
GitHub
commit
41e4949396
133
README.rst
133
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 <https://cmake.org>`_ 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 <https://docs.docker.com/docker-for-mac/>`_ and `Docker for Windows <https://docs.docker.com/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 <https://github.com/dockbuild/dockbuild#readme>`_
|
||||
images use the same method to conveniently isolate the build environment as
|
||||
`dockcross <https://github.com/dockcross/dockcross#readme>`_ 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
|
||||
<https://nbviewer.jupyter.org/format/slides/github/dockcross/cxx-write-once-run-anywhere/blob/master/dockcross_CXX_Write_Once_Run_Anywhere.ipynb#/>`_
|
||||
- `Cross-compiling binaries for multiple architectures with Docker
|
||||
<https://web.archive.org/web/20170912153531/http://blogs.nopcode.org/brainstorm/2016/07/26/cross-compiling-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
|
||||
<https://nbviewer.jupyter.org/format/slides/github/dockcross/cxx-write-once-run-anywhere/blob/master/dockcross_CXX_Write_Once_Run_Anywhere.ipynb#/>`_
|
||||
- `Cross-compiling binaries for multiple architectures with Docker
|
||||
<https://web.archive.org/web/20170912153531/http://blogs.nopcode.org/brainstorm/2016/07/26/cross-compiling-with-docker>`_
|
||||
The key difference is that `dockbuild <https://github.com/dockbuild/dockbuild#readme>`_
|
||||
images use the same method to conveniently isolate the build environment as
|
||||
`dockcross <https://github.com/dockcross/dockcross#readme>`_ but they do **NOT** provide
|
||||
a toolchain file.
|
||||
|
||||
|
||||
---
|
||||
|
||||
Loading…
Reference in New Issue
Block a user