Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve developer build instructions [skip ci][ci skip] #2264

Merged
merged 3 commits into from
May 18, 2020
Merged

Improve developer build instructions [skip ci][ci skip] #2264

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2b1dead
Improve developer guild instructions [skip ci][ci skip]
rfay May 18, 2020
38955ef
Add building container info [skip ci][ci skip]
rfay May 18, 2020
036316e
Add info about automated tests [skip ci][ci skip]
rfay May 18, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
8 changes: 5 additions & 3 deletions build-tools/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Build tools for standard makefile

**These build tools live at https://github.com/drud/build-tools**. If you are viewing this README in any other repository, it's important to know that modifications should **never** be made directly, and instead should be made to the base repository and pulled in via the instructions below.
**These build tools live at <https://github.com/drud/build-tools>**. If you are viewing this README in any other repository, it's important to know that modifications should **never** be made directly, and instead should be made to the base repository and pulled in via the instructions below.

These tools add standard components (sub-makefiles and build scripts) as well as example starters for the Makefile and .circleci/config.yml.

Expand All @@ -25,7 +25,7 @@ chmod +x build_update.sh
* Edit the sub-Makefiles included
* Update the variables at the top of the Makefile

## Additional chores when installing:
## Additional chores when installing

* Add the items from gitignore_example to the .gitignore in each directory that has a Makefile
* Update the project README.md to explain how to build - the target reminders in the paragraph below may be helpful.
Expand Down Expand Up @@ -71,11 +71,13 @@ If you're using Powershell instead of cmd, just prepend an `&` on the command, a
## Installed requirements

You'll need:

* docker-ce (will work with move versions and platforms)
* gnu make
* golang

On windows the building is somewhat more difficult due to the build being bash/linux/make-oriented, but support is provided. You need:

* [chocolatey](https://chocolatey.org/install) installed
* make for Windows 3.81 (Recommended package [choco install make](https://chocolatey.org/packages/make) on chocolatey.org)
* git for windows (Recommended package [choco install git](https://chocolatey.org/packages/git.install))
Expand All @@ -85,4 +87,4 @@ On windows the building is somewhat more difficult due to the build being bash/l

## Golang compiler component

golang projects and static analysis functions like gofmt are built in a container from drud/golang-build-container (from https://github.com/drud/golang-build-container). The version of the container is specified in build-tools.
golang projects and static analysis functions like gofmt are built in a container from drud/golang-build-container (from <https://github.com/drud/golang-build-container).> The version of the container is specified in build-tools.
1 change: 0 additions & 1 deletion build-tools/makefile_components/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,3 @@
Please do not change these files. They're intended to be replaceable globally in all repositories as our needs changed.

If one of these sections does not meet your needs, consider copying its contents into ../Makefile and commenting out the include and adding a comment about what you did and why.

36 changes: 27 additions & 9 deletions docs/developers/building-contributing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,24 @@
# Building, Testing, and Contributing

## Pull Requests and PR Preparation

When preparing your pull request, please use a branch name like "2020_<your_username>_short_description" so that it's easy to track to you.

If you're doing a docs-only PR that does not require full testing, please add "[skip ci][ci skip]" to your commit messages; it saves a lot of testing resources.

## Docker Image changes

If you make changes to a docker image (like ddev-webserver), it won't have any effect unless you:

* You can build an image with a specific tag by going to the image directory (like containers/ddev-webserver) by just doing `make container VERSION=<branchname>` in the containers/ddev-webserver directory.
* Push a container to hub.docker.com. Push with the tag that matches your branch. Pushing to drud/ddev-webserver repo is easy to accomplish with `make push VERSION=<branchname>` **in the container directory**. You might have to use other techniques to push to another repo (`docker push`)
* Update pkg/version/version.go with the WebImg and WebTag that relate to the docker image you pushed.

## Building

If you have `make` and docker, you can build for your environment with just `make`. Since the Makefile uses docker to build, it's not generally essential to install go on your machine, although it will make things easier.
Build the project with `make` and your resulting executable will end up in .gotmp/bin/ddev (for Linux) or .gotmp/bin/windows_amd64/ddev.exe (for Windows) or .gotmp/bin/darwin/ddev (for macOS).

Build/test/check static analysis with:
Build/test/check static analysis with

```
make
Expand All @@ -16,26 +30,30 @@ Build/test/check static analysis with:
make staticrequired
```

The binaries are built into .gotmp/bin; although normal command-line `go build` or `go install` will work (and everything works fine with IDEs like Goland or vscode) the official build technique is via `make` which uses a completely consistent golang-build-container so that the build is identical no matter what machine or OS it might be built on.

## Testing

Normal test invocation is just `make test`. Run a single test with an invocation like `go test -v -run TestDevAddSites ./pkg/...` or `make testpkg TESTARGS="-run TestDevAddSites"`.
Normal test invocation is just `make test`. Run a single test with an invocation like `go test -v -run TestDevAddSites ./pkg/...` or `make testpkg TESTARGS="-run TestDevAddSites"`. The easiest way to run tests is from inside the excellent golang IDE Goland. Just click the arrowhead to the left of the test name.

To see which ddev commands the tests are executing, set the environment variable DDEV_DEBUG=true.

Use GOTEST_SHORT=true to run just one CMS in each test.
Use GOTEST_SHORT=true to run just one CMS in each test, or GOTEST_SHORT=<integer> to run exactly one project type from the list of project types in the [TestSites array](https://github.com/drud/ddev/blob/a4ab2827d8b6e706b2420700045d889a3a69f3f2/pkg/ddevapp/ddevapp_test.go#L43). For example, GOTEST_SHORT=5 will run many tests only against TYPO3.

## Automated testing

Anybody can view the CircleCI automated tests, and they usually show up any problems that are not OS-specific. Just click through on the testing section of the PR to see them.

The Buildkite automated tests require special access, which we typically grant to any PR contributor that asks for it.

## Docker container development
## Docker image development

The docker containers that ddev uses are included in the containers/ directory:
The docker images that ddev uses are included in the containers/ directory:

* containers/ddev-webserver: Provides the web servers (the "web" container).
* containers/ddev-dbserver: Provides the "db" container.
* containers/phpmyadmin: Provides the phpmyadmin (dba) container
* containers/ddev-router: The router image

When changes are made to a container, they have to be temporarily pushed to a tag that is preferably the same as the branch name of the PR, and the tag updated in pkg/version/version.go. Just ask if you need a container pushed to support a PR.
When changes are made to an image, they have to be temporarily pushed to a tag that is preferably the same as the branch name of the PR, and the tag updated in pkg/version/version.go. Just ask if you need a container pushed to support a PR.

## Contributing

Expand Down