12 There are currently two ways we generate the necessary files. We are currently |
12 There are currently two ways we generate the necessary files. We are currently |
13 migrating the build system to use containers so the builds are reproducible. |
13 migrating the build system to use containers so the builds are reproducible. |
14 This is being done on an OS-by-OS basis. Please update this documentation as |
14 This is being done on an OS-by-OS basis. Please update this documentation as |
15 components of the build system change. |
15 components of the build system change. |
16 |
16 |
17 ### Old Build System (currently for `GOOS != "Linux" || GOARCH == "sparc64"`) |
17 ### Old Build System (currently for `GOOS != "linux"`) |
18 |
18 |
19 The old build system generates the Go files based on the C header files |
19 The old build system generates the Go files based on the C header files |
20 present on your system. This means that files |
20 present on your system. This means that files |
21 for a given GOOS/GOARCH pair must be generated on a system with that OS and |
21 for a given GOOS/GOARCH pair must be generated on a system with that OS and |
22 architecture. This also means that the generated code can differ from system |
22 architecture. This also means that the generated code can differ from system |
30 |
30 |
31 To build the files for your current OS and architecture, make sure GOOS and |
31 To build the files for your current OS and architecture, make sure GOOS and |
32 GOARCH are set correctly and run `mkall.sh`. This will generate the files for |
32 GOARCH are set correctly and run `mkall.sh`. This will generate the files for |
33 your specific system. Running `mkall.sh -n` shows the commands that will be run. |
33 your specific system. Running `mkall.sh -n` shows the commands that will be run. |
34 |
34 |
35 Requirements: bash, perl, go |
35 Requirements: bash, go |
36 |
36 |
37 ### New Build System (currently for `GOOS == "Linux" && GOARCH != "sparc64"`) |
37 ### New Build System (currently for `GOOS == "linux"`) |
38 |
38 |
39 The new build system uses a Docker container to generate the go files directly |
39 The new build system uses a Docker container to generate the go files directly |
40 from source checkouts of the kernel and various system libraries. This means |
40 from source checkouts of the kernel and various system libraries. This means |
41 that on any platform that supports Docker, all the files using the new build |
41 that on any platform that supports Docker, all the files using the new build |
42 system can be generated at once, and generated files will not change based on |
42 system can be generated at once, and generated files will not change based on |
50 To build all the files under the new build system, you must be on an amd64/Linux |
50 To build all the files under the new build system, you must be on an amd64/Linux |
51 system and have your GOOS and GOARCH set accordingly. Running `mkall.sh` will |
51 system and have your GOOS and GOARCH set accordingly. Running `mkall.sh` will |
52 then generate all of the files for all of the GOOS/GOARCH pairs in the new build |
52 then generate all of the files for all of the GOOS/GOARCH pairs in the new build |
53 system. Running `mkall.sh -n` shows the commands that will be run. |
53 system. Running `mkall.sh -n` shows the commands that will be run. |
54 |
54 |
55 Requirements: bash, perl, go, docker |
55 Requirements: bash, go, docker |
56 |
56 |
57 ## Component files |
57 ## Component files |
58 |
58 |
59 This section describes the various files used in the code generation process. |
59 This section describes the various files used in the code generation process. |
60 It also contains instructions on how to modify these files to add a new |
60 It also contains instructions on how to modify these files to add a new |
61 architecture/OS or to add additional syscalls, types, or constants. Note that |
61 architecture/OS or to add additional syscalls, types, or constants. Note that |
62 if you are using the new build system, the scripts cannot be called normally. |
62 if you are using the new build system, the scripts/programs cannot be called normally. |
63 They must be called from within the docker container. |
63 They must be called from within the docker container. |
64 |
64 |
65 ### asm files |
65 ### asm files |
66 |
66 |
67 The hand-written assembly file at `asm_${GOOS}_${GOARCH}.s` implements system |
67 The hand-written assembly file at `asm_${GOOS}_${GOARCH}.s` implements system |
79 When porting Go to an new architecture/OS, this file must be implemented for |
79 When porting Go to an new architecture/OS, this file must be implemented for |
80 each GOOS/GOARCH pair. |
80 each GOOS/GOARCH pair. |
81 |
81 |
82 ### mksysnum |
82 ### mksysnum |
83 |
83 |
84 Mksysnum is a script located at `${GOOS}/mksysnum.pl` (or `mksysnum_${GOOS}.pl` |
84 Mksysnum is a Go program located at `${GOOS}/mksysnum.go` (or `mksysnum_${GOOS}.go` |
85 for the old system). This script takes in a list of header files containing the |
85 for the old system). This program takes in a list of header files containing the |
86 syscall number declarations and parses them to produce the corresponding list of |
86 syscall number declarations and parses them to produce the corresponding list of |
87 Go numeric constants. See `zsysnum_${GOOS}_${GOARCH}.go` for the generated |
87 Go numeric constants. See `zsysnum_${GOOS}_${GOARCH}.go` for the generated |
88 constants. |
88 constants. |
89 |
89 |
90 Adding new syscall numbers is mostly done by running the build on a sufficiently |
90 Adding new syscall numbers is mostly done by running the build on a sufficiently |
91 new installation of the target OS (or updating the source checkouts for the |
91 new installation of the target OS (or updating the source checkouts for the |
92 new build system). However, depending on the OS, you make need to update the |
92 new build system). However, depending on the OS, you make need to update the |
93 parsing in mksysnum. |
93 parsing in mksysnum. |
94 |
94 |
95 ### mksyscall.pl |
95 ### mksyscall.go |
96 |
96 |
97 The `syscall.go`, `syscall_${GOOS}.go`, `syscall_${GOOS}_${GOARCH}.go` are |
97 The `syscall.go`, `syscall_${GOOS}.go`, `syscall_${GOOS}_${GOARCH}.go` are |
98 hand-written Go files which implement system calls (for unix, the specific OS, |
98 hand-written Go files which implement system calls (for unix, the specific OS, |
99 or the specific OS/Architecture pair respectively) that need special handling |
99 or the specific OS/Architecture pair respectively) that need special handling |
100 and list `//sys` comments giving prototypes for ones that can be generated. |
100 and list `//sys` comments giving prototypes for ones that can be generated. |
101 |
101 |
102 The mksyscall.pl script takes the `//sys` and `//sysnb` comments and converts |
102 The mksyscall.go program takes the `//sys` and `//sysnb` comments and converts |
103 them into syscalls. This requires the name of the prototype in the comment to |
103 them into syscalls. This requires the name of the prototype in the comment to |
104 match a syscall number in the `zsysnum_${GOOS}_${GOARCH}.go` file. The function |
104 match a syscall number in the `zsysnum_${GOOS}_${GOARCH}.go` file. The function |
105 prototype can be exported (capitalized) or not. |
105 prototype can be exported (capitalized) or not. |
106 |
106 |
107 Adding a new syscall often just requires adding a new `//sys` function prototype |
107 Adding a new syscall often just requires adding a new `//sys` function prototype |
158 signal numbers, and constants. Generated by `mkerrors.sh` (see above). |
158 signal numbers, and constants. Generated by `mkerrors.sh` (see above). |
159 |
159 |
160 ### `zsyscall_${GOOS}_${GOARCH}.go` |
160 ### `zsyscall_${GOOS}_${GOARCH}.go` |
161 |
161 |
162 A file containing all the generated syscalls for a specific GOOS and GOARCH. |
162 A file containing all the generated syscalls for a specific GOOS and GOARCH. |
163 Generated by `mksyscall.pl` (see above). |
163 Generated by `mksyscall.go` (see above). |
164 |
164 |
165 ### `zsysnum_${GOOS}_${GOARCH}.go` |
165 ### `zsysnum_${GOOS}_${GOARCH}.go` |
166 |
166 |
167 A list of numeric constants for all the syscall number of the specific GOOS |
167 A list of numeric constants for all the syscall number of the specific GOOS |
168 and GOARCH. Generated by mksysnum (see above). |
168 and GOARCH. Generated by mksysnum (see above). |