Author: Rob Pike Date: 2014
Status: this proposal was [adopted for the Go 1.4 release] (https://go.dev/doc/go1.4#major_library_changes).
syscall package as it stands today has several problems:
syscall, is different for every system, but godoc only shows the variant for its own native environment. Moreover, the documentation is sorely lacking anyway. Most functions have no doc comment at all.
This proposal is an attempt to ameliorate these issues.
The proposal has several components. In no particular order:
syscall package will not be updated in future releases, not even to keep pace with changes in operating systems it references. For example, if the value of a kernel constant changes in a future NetBSD release, package
syscall will not be updated to reflect that.
go.sys, will be created.
go.sys, there will be three packages, independent of syscall, called
windows, and the current
syscall package's contents will be broken apart as appropriate and installed in those packages. (This split expresses the fundamental interface differences between the systems, permitting some source-level portability, but within the packages build tags will still be needed to separate out architectures and variants (darwin, linux)). These are the packages we expect all external Go packages to migrate to when they need support for system calls. Because they are distinct, they are easier to curate, easier to examine with godoc, and may be easier to keep well documented. This layout also makes it clearer how to write cross-platform code: by separating system-dependent elements into separately imported components.
go.sys repositories will be updated as operating systems evolve.
syscall package will direct users to the new repository. Although the
syscall package will continue to exist and work as well as feasible, all new public development will occur in
go.sys packages, although it is likely some of the subrepositories, such as
go.sys repository will be curated by the Go team. Separating it out of the main repository makes it more practical to automate some of the maintenance, for example to create packages automatically by exhaustive processing of system include files.
syscall package since 1.3 will be migrated to the
Note that we cannot clean up the existing
syscall package to any meaningful extent because of the compatibility guarantee. We can freeze and, in effect, deprecate it, however.
We propose to complete these changes before the September 1, 2014 deadline for Go 1.4.