github.com/fcwu/docker@v1.4.2-0.20150115145920-2a69ca89f0df/docs/sources/contributing/devenvironment.md (about)

     1  page_title: Setting Up a Dev Environment
     2  page_description: Guides on how to contribute to docker
     3  page_keywords: Docker, documentation, developers, contributing, dev environment
     4  
     5  # Setting Up a Dev Environment
     6  
     7  To make it easier to contribute to Docker, we provide a standard
     8  development environment. It is important that the same environment be
     9  used for all tests, builds and releases. The standard development
    10  environment defines all build dependencies: system libraries and
    11  binaries, go environment, go dependencies, etc.
    12  
    13  ## Install Docker
    14  
    15  Docker's build environment itself is a Docker container, so the first
    16  step is to install Docker on your system.
    17  
    18  You can follow the [install instructions most relevant to your
    19  system](https://docs.docker.com/installation/). Make sure you
    20  have a working, up-to-date docker installation, then continue to the
    21  next step.
    22  
    23  ## Install tools used for this tutorial
    24  
    25  Install `git`; honest, it's very good. You can use
    26  other ways to get the Docker source, but they're not anywhere near as
    27  easy.
    28  
    29  Install `make`. This tutorial uses our base Makefile
    30  to kick off the docker containers in a repeatable and consistent way.
    31  Again, you can do it in other ways but you need to do more work.
    32  
    33  ## Check out the Source
    34  
    35      $ git clone https://git@github.com/docker/docker
    36      $ cd docker
    37  
    38  To checkout a different revision just use `git checkout`
    39  with the name of branch or revision number.
    40  
    41  ## Build the Environment
    42  
    43  This following command builds a development environment using the
    44  `Dockerfile` in the current directory. Essentially, it installs all
    45  the build and runtime dependencies necessary to build and test Docker.
    46  Your first build will take some time to complete. On Linux systems:
    47  
    48      $ sudo make build
    49      
    50  On Mac OS X, from within the `boot2docker` shell:
    51  
    52      $ make build
    53  
    54  > **Note**:
    55  > On Mac OS X, the Docker make targets such as `build`, `binary`, and `test`
    56  > should **not** be built by the 'root' user. Therefore, you shouldn't use `sudo` when 
    57  > running these commands on OS X. 
    58  
    59  If the build is successful, congratulations! You have produced a clean
    60  build of docker, neatly encapsulated in a standard build environment.
    61  
    62  
    63  ## Build the Docker Binary
    64  
    65  To create the Docker binary, run this command:
    66  
    67      $ sudo make binary
    68  
    69  This will create the Docker binary in `./bundles/<version>-dev/binary/`. If you
    70  do not see files in the `./bundles` directory in your host, your `BINDDIR`
    71  setting is not set quite right. You want to run the following command: 
    72      
    73      $ sudo make BINDDIR=. binary 
    74  
    75  If you are on a non-Linux platform, e.g., OSX, you'll want to run `make cross`
    76  or `make BINDDIR=. cross`.
    77  
    78  ### Using your built Docker binary
    79  
    80  The binary is available outside the container in the directory
    81  `./bundles/<version>-dev/binary/`. You can swap your
    82  host docker executable with this binary for live testing - for example,
    83  on ubuntu:
    84  
    85      $ sudo service docker stop ; sudo cp $(which docker) $(which docker)_ ; sudo cp ./bundles/<version>-dev/binary/docker-<version>-dev $(which docker);sudo service docker start
    86  
    87  > **Note**: 
    88  > Its safer to run the tests below before swapping your hosts docker binary.
    89  
    90  ## Run the Tests
    91  
    92  To execute the test cases, run this command:
    93  
    94      $ sudo make test
    95  
    96  If the test are successful then the tail of the output should look
    97  something like this
    98  
    99      --- PASS: TestWriteBroadcaster (0.00 seconds)
   100      === RUN TestRaceWriteBroadcaster
   101      --- PASS: TestRaceWriteBroadcaster (0.00 seconds)
   102      === RUN TestTruncIndex
   103      --- PASS: TestTruncIndex (0.00 seconds)
   104      === RUN TestCompareKernelVersion
   105      --- PASS: TestCompareKernelVersion (0.00 seconds)
   106      === RUN TestHumanSize
   107      --- PASS: TestHumanSize (0.00 seconds)
   108      === RUN TestParseHost
   109      --- PASS: TestParseHost (0.00 seconds)
   110      === RUN TestParseRepositoryTag
   111      --- PASS: TestParseRepositoryTag (0.00 seconds)
   112      === RUN TestGetResolvConf
   113      --- PASS: TestGetResolvConf (0.00 seconds)
   114      === RUN TestParseRelease
   115      --- PASS: TestParseRelease (0.00 seconds)
   116      === RUN TestDependencyGraphCircular
   117      --- PASS: TestDependencyGraphCircular (0.00 seconds)
   118      === RUN TestDependencyGraph
   119      --- PASS: TestDependencyGraph (0.00 seconds)
   120      PASS
   121      ok      github.com/docker/docker/utils        0.017s
   122  
   123  If $TESTFLAGS is set in the environment, it is passed as extra arguments
   124  to `go test`. You can use this to select certain tests to run, e.g.,
   125  
   126      $ TESTFLAGS='-test.run \^TestBuild\$' make test
   127  
   128  If the output indicates "FAIL" and you see errors like this:
   129  
   130      server.go:1302 Error: Insertion failed because database is full: database or disk is full
   131  
   132      utils_test.go:179: Error copy: exit status 1 (cp: writing '/tmp/docker-testd5c9-[...]': No space left on device
   133  
   134  Then you likely don't have enough memory available the test suite. 2GB
   135  is recommended.
   136  
   137  ## Use Docker
   138  
   139  You can run an interactive session in the newly built container:
   140  
   141      $ sudo make shell
   142  
   143      # type 'exit' or Ctrl-D to exit
   144  
   145  ## Build And View The Documentation
   146  
   147  If you want to read the documentation from a local website, or are
   148  making changes to it, you can build the documentation and then serve it
   149  by:
   150  
   151      $ sudo make docs
   152      
   153      # when its done, you can point your browser to http://yourdockerhost:8000
   154      # type Ctrl-C to exit
   155  
   156  **Need More Help?**
   157  
   158  If you need more help then hop on to the [#docker-dev IRC
   159  channel](irc://chat.freenode.net#docker-dev) or post a message on the
   160  [Docker developer mailing
   161  list](https://groups.google.com/d/forum/docker-dev).