Makefile pour un projet Go (2017)

Vincent Bernat

Mise à jour (07.2019)

Go 1.11 in­tro­duit le concept de mo­dule pour gé­rer les dé­pen­dances sans uti­li­ser GOPATH. Bien que cer­tains as­pects du Makefile pré­senté ici res­tent per­ti­nents (construc­tion des ou­tils an­nexes, exé­cu­tion des tests), le point prin­ci­pal de­vient sans ob­jet. Je­tez un œil sur la mise à jour de cet article.

Très tôt, j’ai pris en grippe le prin­cipe du GOPATH mis avant par Go : je ne veux en au­cun cas mé­lan­ger mon propre code avec ce­lui des dé­pen­dances. Heu­reu­se­ment, ce pro­blème com­mence à être ac­cepté par les prin­ci­paux au­teurs. Entre temps, il est tou­jours pos­sible de tra­vailler de ma­nière plus clas­sique en uti­li­sant des ou­tils tels que gb ou en écri­vant son propre Makefile.

Pour cette der­nière so­lu­tion, vous pou­vez étu­dier l’exemple de Fi­lippo Val­sorda ou ma propre réa­li­sa­tion que je dé­cris plus en dé­tail dans cet article.

Structure du projet#

Pour une ap­pli­ca­tion (par op­po­si­tion à une bi­blio­thèque), le ven­do­ring est es­sen­tiel1: il n’est ac­tuel­le­ment pas pos­sible de sup­po­ser que les dé­pen­dances ne vont pas in­tro­duire dans le fu­tur des chan­ge­ments in­com­pa­tibles. Cer­tains pa­quets uti­lisent des URL ver­sion­nées mais la plu­part ne le font pas. Il n’existe pas en­core d’ou­til stan­dard pour gé­rer les dé­pen­dances. Mon choix per­son­nel est d’op­ter pour le ven­do­ring de toutes les dé­pen­dances avec Glide2.

Il est de bon usage de dé­cou­per son ap­pli­ca­tion en dif­fé­rents pa­quets et de ne lais­ser que le mi­ni­mum dans le pa­quet prin­ci­pal. Dans l’exemple hellogopher, fourni à titre d’illus­tra­tion avec le Makefile, la ligne de com­mande est gé­rée dans le pa­quet cmd tan­dis que la « lo­gique » de l’ap­pli­ca­tion se trouve dans le pa­quet hello :

.
├── cmd/
│   ├── hello.go
│   ├── root.go
│   └── version.go
├── glide.lock (généré)
├── glide.yaml
├── vendor/ (vide, contiendra les dépendances)
├── hello/
│   ├── root.go
│   └── root_test.go
├── main.go
├── Makefile
└── README.md

Fonctionnalités#

Ex­plo­rons les dif­fé­rentes fonc­tion­na­li­tés pro­po­sées par le Makefile.

Gestion du GOPATH#

Comme toutes les dé­pen­dances se trouvent dans le ré­per­toire vendor/, seul notre propre code doit être placé dans le GOPATH :

PACKAGE  = hellogopher
GOPATH   = $(CURDIR)/.gopath
BASE     = $(GOPATH)/src/$(PACKAGE)

$(BASE):
    @mkdir -p $(dir $@)
    @ln -sf $(CURDIR) $@

Le che­min d’im­port de base est hellogopher et non github.​com/​vincentbernat/​hellogopher : cela ré­duit la ver­bo­sité des im­ports et per­met de dis­tin­guer plus fa­ci­le­ment nos propres pa­quets des dé­pen­dances. Tou­te­fois, cela rend l’ap­pli­ca­tion in­com­pa­tible avec go get. C’est un choix per­son­nel qui peut être mo­di­fié en ajus­tant la va­riable $(PACKAGE).

Nous créons sim­ple­ment un lien sym­bo­lique de .gopath/​src/​hellogopher vers la ra­cine de notre dé­pôt. La va­riable d’en­vi­ron­ne­ment GOPATH est au­to­ma­ti­que­ment ex­por­tée pour les com­mandes in­vo­quées par les re­cettes du Makefile. La plu­part des ou­tils fonc­tionnent alors cor­rec­te­ment une fois le ré­per­toire cou­rant changé pour $(BASE). Par exemple, le code sui­vant s’oc­cupe de la construc­tion de l’exé­cutable :

.PHONY: all
all: | $(BASE)
    cd $(BASE) && $(GO) build -o bin/$(PACKAGE) main.go

Vendoring#

Glide fonc­tionne à la ma­nière de l’ou­til Bund­ler pour Ruby. Les pa­quets né­ces­saires ainsi qu’un en­semble de contraintes sont spé­ci­fiés dans le fi­chier glide.​yaml. Glide construit un fi­chier glide.​lock conte­nant les ver­sions exactes de chaque dé­pen­dance (y com­pris les dé­pen­dances de dé­pen­dances) et les té­lé­charge dans le ré­per­toire vendor/. Il est pos­sible de ne pla­cer que glide.​yaml dans le sys­tème de ges­tion de sources, mais aussi glide.​lock, voire le ré­per­toire vendor/. L’ou­til stan­dard de ges­tion des dé­pen­dances de Go, en cours de concep­tion, uti­lise une mé­tho­do­lo­gie si­milaire.

Nous dé­fi­nis­sons deux règles3 :

GLIDE = glide

glide.lock: glide.yaml | $(BASE)
    cd $(BASE) && $(GLIDE) update
    @touch $@
vendor: glide.lock | $(BASE)
    cd $(BASE) && $(GLIDE) --quiet install
    @ln -sf . vendor/src
    @touch $@

Une va­riable est uti­li­sée pour in­vo­quer glide. Cela per­met à l’uti­li­sa­teur de four­nir un em­pla­ce­ment al­ter­na­tif (par exemple, avec make GLIDE=$GOPATH/​bin/glide).

Outils tiers#

Lorsqu’un pro­jet a be­soin d’ou­tils tiers, nous pou­vons soit nous at­tendre à ce qu’ils soient déjà ins­tal­lés ou bien les com­pi­ler dans notre GOPATH privé. Par exemple, voici une règle pour exé­cu­ter golint :

BIN    = $(GOPATH)/bin
GOLINT = $(BIN)/golint

$(BIN)/golint: | $(BASE) # ❶
    go get github.com/golang/lint/golint

.PHONY: lint
lint: vendor | $(BASE) $(GOLINT) # ❷
    @cd $(BASE) && ret=0 && for pkg in $(PKGS); do \
        test -z "$$($(GOLINT) $$pkg | tee /dev/stderr)" || ret=1 ; \
     done ; exit $$ret

Comme pour glide, l’uti­li­sa­teur a pos­si­bi­lité de chan­ger le che­min à uti­li­ser pour golint. Par dé­faut, nous uti­li­sons une co­pie pri­vée mais un autre che­min peut être fourni avec make GOLINT=/​usr/​bin/golint.

En ❶, la re­cette de construc­tion de golint uti­lise go get4 pour té­lé­char­ger et construire l’exé­cu­table. En ❷, la règle pour lint exé­cute golint sur chaque pa­quet spé­ci­fié dans la va­riable $(PKGS). Nous dé­taillons cette der­nière dans la sec­tion suivante.

Restreindre la liste des paquets à utiliser#

Cer­taines com­mandes né­ces­sitent une liste de pa­quets. Parce que nous uti­li­sons un ré­per­toire vendor/, nous ne pou­vons pas uti­li­ser ./... comme rac­courci pour tous les pa­quets. Cela condui­rait par exemple à dé­rou­ler les tests sur les dé­pen­dances5. Nous de­vons donc com­po­ser une liste des pa­quets à utiliser :

PKGS = $(or $(PKG), $(shell cd $(BASE) && \
    env GOPATH=$(GOPATH) $(GO) list ./... | grep -v "^$(PACKAGE)/vendor/"))

Si l’uti­li­sa­teur a fourni une va­riable $(PKG), celle-ci est uti­li­sée di­rec­te­ment. Par exemple, make lint PKG=​hellogopher/​cmd per­met d’exé­cu­ter la com­mande golint sur le pa­quet cmd. Dans ce cas, l’uti­li­sa­tion de PKG est plus in­tui­tive que PKGS.

Dans le cas contraire, go list ./... per­met d’ob­te­nir une liste de tous les pa­quets. Les pa­quets is­sus du ré­per­toire vendor/ sont re­ti­rés de celle-ci.

Mise à jour (03.2018)

De­puis Go 1.9, ./... n’in­clut plus les pa­quets dans le ré­per­toire vendor/.

Tests#

Voici les règles per­met­tant d’exé­cu­ter les tests :

TIMEOUT = 20
TEST_TARGETS := test-default test-bench test-short test-verbose test-race
.PHONY: $(TEST_TARGETS) check test tests
test-bench:   ARGS=-run=__absolutelynothing__ -bench=.
test-short:   ARGS=-short
test-verbose: ARGS=-v
test-race:    ARGS=-race
$(TEST_TARGETS): test

check test tests: fmt lint vendor | $(BASE)
    @cd $(BASE) && $(GO) test -timeout $(TIMEOUT)s $(ARGS) $(PKGS)

L’uti­li­sa­teur peut in­vo­quer les tests de dif­fé­rentes façons :

  • make test lance tous les tests ;
  • make test TIMEOUT=10 im­plique une du­rée li­mite de 10 se­condes par test ;
  • make test PKG=​hellogopher/​cmd exé­cute les tests pour le pa­quet cmd ;
  • make test ARGS="-v -short" uti­lise les ar­gu­ments fournis ;
  • make test-race exé­cute les tests en ac­ti­vant la dé­tec­tion des pro­blèmes d’ac­cès concurrents.

Couverture des tests#

go test per­met éga­le­ment de dé­ter­mi­ner la cou­ver­ture des tests. Mal­heu­reu­se­ment, l’ou­til est très ru­di­men­taire et ne per­met de gé­rer qu’un seul pa­quet à la fois. Il faut éga­le­ment ex­pli­ci­te­ment lis­ter tous les pa­quets à ins­tru­men­ter. Dans le cas contraire, seul le pa­quet testé est ins­tru­menté. De plus, les temps de com­pi­la­tion sont pro­hi­bi­tifs si trop de pa­quets sont ins­tru­men­tés. En­fin, afin d’ob­te­nir un rap­port com­pa­tible avec Jen­kins, quelques ou­tils ad­di­tion­nels sont né­cessaires.

COVERAGE_MODE    = atomic
COVERAGE_PROFILE = $(COVERAGE_DIR)/profile.out
COVERAGE_XML     = $(COVERAGE_DIR)/coverage.xml
COVERAGE_HTML    = $(COVERAGE_DIR)/index.html

.PHONY: test-coverage test-coverage-tools
test-coverage-tools: | $(GOCOVMERGE) $(GOCOV) $(GOCOVXML) # ❸
test-coverage: COVERAGE_DIR := $(CURDIR)/test/coverage.$(shell date -Iseconds)
test-coverage: fmt lint vendor test-coverage-tools | $(BASE)
    @mkdir -p $(COVERAGE_DIR)/coverage
    @cd $(BASE) && for pkg in $(PKGS); do \ # ❹
        $(GO) test \
            -coverpkg=$$($(GO) list -f '{{ join .Deps "\n" }}' $$pkg | \
                    grep '^$(PACKAGE)/' | grep -v '^$(PACKAGE)/vendor/' | \
                    tr '\n' ',')$$pkg \
            -covermode=$(COVERAGE_MODE) \
            -coverprofile="$(COVERAGE_DIR)/coverage/`echo $$pkg | tr "/" "-"`.cover" $$pkg ;\
     done
    @$(GOCOVMERGE) $(COVERAGE_DIR)/coverage/*.cover > $(COVERAGE_PROFILE)
    @$(GO) tool cover -html=$(COVERAGE_PROFILE) -o $(COVERAGE_HTML)
    @$(GOCOV) convert $(COVERAGE_PROFILE) | $(GOCOVXML) > $(COVERAGE_XML)

En ❸, un cer­tain nombre d’ou­tils sont requis :

  • gocovmerge per­met de com­bi­ner plu­sieurs pro­fils en un seul,
  • gocov-xml conver­tit le rap­port au for­mat Co­bertura,
  • gocov conver­tit le rap­port en un for­mat uti­li­sable par gocov-xml.

Les règles pour construire ces ou­tils sont si­mi­laires à celle pour golint.

En ❹, pour chaque pa­quet à tes­ter, nous exé­cu­tons go test avec l’ar­gu­ment -coverprofile. La liste des pa­quets à ins­tru­men­ter est don­née à l’ar­gu­ment -coverpkg en uti­li­sant go list pour ex­traire les dé­pen­dances du pa­quet en cours de test et en ne conser­vant que nos propres paquets.

Conclusion#

Bien que l’in­té­rêt prin­ci­pal de ce Makefile soit de tra­vailler sans GOPATH, c’est aussi un bon moyen de ca­cher la com­plexité de cer­taines opé­rations.

Les ex­traits four­nis ici ont été sim­pli­fiés. Je­tez un œil sur le ré­sul­tat fi­nal pour plus de détails !