1# Hacking Guide
2
3## Overview
4
5This guide contains instructions for building artifacts contained in this repository.
6
7### Go
8
9This spec includes several Go packages, and a command line tool considered to be a reference implementation of the OCI image specification.
10
11Prerequisites:
12* Go - current release only, earlier releases are not supported
13* make
14
15The following make targets are relevant for any work involving the Go packages.
16
17### Linting
18
19The included Go source code is being examined for any linting violations not included in the standard Go compiler. Linting is done using [gometalinter](https://github.com/alecthomas/gometalinter).
20
21Invocation:
22```
23$ make lint
24```
25
26### Tests
27
28This target executes all Go based tests.
29
30Invocation:
31```
32$ make test
33$ make validate-examples
34```
35
36### Virtual schema http/FileSystem
37
38The `schema` validator uses a virtual [http/FileSystem](https://golang.org/pkg/net/http/#FileSystem) to load the JSON schema files for validating OCI images and/or manifests.
39The virtual filesystem is generated using the `esc` tool and compiled into consumers of the `schema` package so the JSON schema files don't have to be distributed along with and consumer binaries.
40
41Whenever changes are being done in any of the `schema/*.json` files, one must refresh the generated virtual filesystem.
42Otherwise schema changes will not be visible inside `schema` consumers.
43
44Prerequisites:
45* [esc](https://github.com/mjibson/esc)
46
47Invocation:
48```
49$ make schema-fs
50```
51
52### JSON schema formatting
53
54This target auto-formats all JSON files in the `schema` directory using the `jq` tool.
55
56Prerequisites:
57* [jq](https://stedolan.github.io/jq/) >=1.5
58
59Invocation:
60```
61$ make fmt
62```
63
64### OCI image specification PDF/HTML documentation files
65
66This target generates a PDF/HTML version of the OCI image specification.
67
68Prerequisites:
69* [Docker](https://www.docker.com/)
70
71Invocation:
72```
73$ make docs
74```
75
76### License header check
77
78This target checks if the source code includes necessary headers.
79
80Invocation:
81```
82$ make check-license
83```
84
85### Clean build artifacts
86
87This target cleans all generated/compiled artifacts.
88
89Invocation:
90```
91$ make clean
92```
93
94### Create PNG images from dot files
95
96This target generates PNG image files from DOT source files in the `img` directory.
97
98Prerequisites:
99* [graphviz](http://www.graphviz.org/)
100
101Invocation:
102```
103$ make img/media-types.png
104```
105