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