Skip to content

Commit

Permalink
correct references to Microsoft build of Go
Browse files Browse the repository at this point in the history
  • Loading branch information
qmuntal committed Feb 10, 2025
1 parent eefb598 commit 4ee4caa
Show file tree
Hide file tree
Showing 17 changed files with 76 additions and 76 deletions.
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,17 +108,17 @@ The first step is to clone this repository using Git and check out the desired
tag or commit. The `zip` file that GitHub offers for download is incomplete: it
doesn't include the `go` submodule.

If you want to contribute to the Microsoft Go project, read the [Developer
If you want to contribute to the Microsoft for Go developers project, read the [Developer
Guide](eng/doc/DeveloperGuide.md). It lists the steps we recommend to set up a
Microsoft Go development environment, execute your first Microsoft Go build, run
Microsoft build of Go development environment, execute your first build, run
the standard library test suite, and contribute a PR.

If you just want to build Microsoft Go on your own machine, you may find it more
If you just want to build on your own machine, you may find it more
convenient to use the tools provided by the `eng/run.ps1` script. We use this
script for CI builds. See [eng/README.md](eng/README.md) for more details about
`eng/run.ps1` and other repository infrastructure.

Once built, the Microsoft Go binary is found at `go/bin/go`.
Once built, the Microsoft build of Go binary is found at `go/bin/go`.

## Contributing

Expand Down
2 changes: 1 addition & 1 deletion docs/go1.23.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# Microsoft Go 1.23 release notes
# Microsoft build of Go 1.23 release notes

After the release of 1.23, 1.21 is no longer supported, per the [Go release policy](https://go.dev/doc/devel/release).
8 changes: 4 additions & 4 deletions eng/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,12 +64,12 @@ complete, to match the content of the official binary releases of Go.

## Patch files

The Microsoft Go repository uses patch files to store changes to the `go`
The Microsoft build of Go repository uses patch files to store changes to the `go`
submodule. The patch files are found in [`/patches`](/patches).

We created [the `git-go-patch` tool][git-go-patch] to develop and maintain the
patch files. We wrote this tool specifically for the Microsoft Go project. It's
a Go program that can be invoked as `git go-patch` after it's installed. See
patch files. We wrote this tool specifically for the Microsoft for Go developers project.
It's a Go program that can be invoked as `git go-patch` after it's installed. See
[the `git-go-patch` readme][git-go-patch] for more information.

We also have some utilities in this repository to apply patches without
Expand All @@ -79,7 +79,7 @@ installing `git-go-patch`:
patches.
* Pass `-commits` to apply each patch as a separate commit.
* `pwsh eng/run.ps1 build -refresh` refreshes the submodule and applies patches
and then goes on to build Microsoft Go.
and then goes on to build the Microsoft build of Go.

The patch files are ordinary Git patches and can also be applied manually
without any custom tooling. Git commands like [`git
Expand Down
2 changes: 1 addition & 1 deletion eng/_util/cmd/sign/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# `sign` and the Microsoft Go signing infrastructure
# `sign` and the Microsoft build of Go signing infrastructure

Most of the logic for signing (extracting files, repackaging, creating checksums) is implemented by this `sign` command.

Expand Down
2 changes: 1 addition & 1 deletion eng/_util/cmd/sign/sign.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ import (
)

const description = `
This command signs build artifacts using MicroBuild. It is used in the Microsoft Go build pipeline.
This command signs build artifacts using MicroBuild. It is used in the Microsoft build of Go build pipeline.
Use '-n' to test the command locally.
Signs in multiple passes. Some steps only apply to certain types of archives:
Expand Down
28 changes: 14 additions & 14 deletions eng/_util/go-install.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@

<#
.SYNOPSIS
Installs Microsoft Go
Installs the Microsoft build of Go
.DESCRIPTION
Installs the Microsoft Go toolset.
Installs the Microsoft build of Go.
Note that the intended use of this script is for Continuous Integration (CI) scenarios, where:
- The toolset needs to be installed without user interaction and without admin rights.
- The toolset installation doesn't need to persist across multiple CI runs.
Visit https://github.com/microsoft/go for a list of other ways to install Microsoft Go.
Visit https://github.com/microsoft/go for a list of other ways to install the Microsoft build of Go.
.PARAMETER Version
Default: Latest
Expand All @@ -21,11 +21,11 @@
examples: go1.18, go1.23
- 3-part version in format go1.A.B - latest revision of a specific release.
examples: go1.18.0, go1.23.1
- 4-part version in format go1.A.B-C - a specific revision of Microsoft Go, immutable.
- 4-part version in format go1.A.B-C - a specific revision of the Microsoft build of Go, immutable.
examples: go1.18.0-1, go1.23.1-3
Microsoft Go doesn't publish prereleases, so they are not available.
The Microsoft build of Go doesn't publish prereleases, so they are not available.
.PARAMETER InstallDir
Path to where to install Microsoft Go. Note that if a directory is given, GOROOT is placed
Path to where to install the Microsoft build of Go. Note that if a directory is given, GOROOT is placed
directly in that directory.
Default: <auto> - a folder automatically selected inside LocalApplicationData as evaluated by PowerShell.
Example auto on Windows: C:\Users\myself\AppData\Local\microsoft-go\<version>
Expand All @@ -42,9 +42,9 @@
Possible values are: <auto>, amd64, x64, 386, x86, arm64, arm
.PARAMETER DryRun
If set, it will not perform installation. Instead, it displays what command line to use to
consistently install currently requested version of Microsoft Go. For example, if you specify
Version 'Latest', it will print a command with the specific 4-part version so this command can
be used deterministicly in a build script.
consistently install currently requested version of the Microsoft build of Go. For example,
if you specify Version 'Latest', it will print a command with the specific 4-part version
so this command can be used deterministicly in a build script.
It also prints the location the binaries would have been installed to.
.PARAMETER NoPath
By default, this script will update the environment variable PATH for the current process to
Expand Down Expand Up @@ -75,10 +75,10 @@
Displays diagnostics information.
.EXAMPLE
go-install.ps1
Installs the latest released Microsoft Go version.
Installs the latest released Microsoft build of Go version.
.EXAMPLE
go-install.ps1 -Version Previous
Installs the latest version of the previous major (1.X) version of Microsoft Go.
Installs the latest version of the previous major (1.X) version of the Microsoft build of Go.
#>
[cmdletbinding()]
param(
Expand Down Expand Up @@ -802,12 +802,12 @@ if ($Help) {
exit
}

Say "Microsoft Go Install Script version $MicrosoftGoInstallScriptVersion"
Say "Microsoft build of Go Install Script version $MicrosoftGoInstallScriptVersion"

Say-Verbose "Note that the intended use of this script is for Continuous Integration (CI) scenarios, where:"
Say-Verbose "- The toolset needs to be installed without user interaction and without admin rights."
Say-Verbose "- The toolset installation doesn't need to persist across multiple CI runs."
Say-Verbose "Visit https://github.com/microsoft/go for a list of other ways to install Microsoft Go.`r`n"
Say-Verbose "Visit https://github.com/microsoft/go for a list of other ways to install the Microsoft build of Go.`r`n"

Measure-Action "Product discovery" {
$script:CLIArchitecture = Get-CLIArchitecture-From-Architecture $Architecture
Expand Down Expand Up @@ -835,7 +835,7 @@ Say-Verbose "Found download link $DownloadLink with version $SpecificVersion"
if (-Not $DryRun) {
Say-Verbose "Checking if the version $SpecificVersion is already installed"
if (Is-ToolsetInstalled -InstallRoot $InstallRoot -SpecificVersion $SpecificVersion) {
Say "Microsoft Go version '$SpecificVersion' is already installed."
Say "The Microsoft build of Go version '$SpecificVersion' is already installed."
Measure-Action "Setting up shell environment" { Prepend-ToolsetPathEnv -InstallRoot $InstallRoot -SpecificVersion $SpecificVersion }
return
}
Expand Down
22 changes: 11 additions & 11 deletions eng/doc/CrossPlatformCryptography.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,34 @@
# Cross-Platform Cryptography in Microsoft Go
# Cross-Platform Cryptography in the Microsoft build of Go

Cryptographic operations in Microsoft Go are delegated to the operating system (OS) libraries in some conditions.
The high level conditions and the benefits of delegating cryptographic operations are described in the [Microsoft Go FIPS README](./fips/README.md).
Cryptographic operations in the Microsoft build of Go are delegated to the operating system (OS) libraries in some conditions.
The high level conditions and the benefits of delegating cryptographic operations are described in the [Microsoft build of Go FIPS README](./fips/README.md).
At a fine-grained level, Go apps will fall back to the native Go implementation of an algorithm if the OS libraries don't support it.
This article identifies the features that are supported on each platform.

This article assumes you have a working familiarity with cryptography in Go.

## Platform support

Microsoft Go supports the following platforms:
The Microsoft build of Go supports the following platforms:

### Windows

On Windows, Microsoft Go uses the [CNG library (Cryptography API: Next Generation)](https://learn.microsoft.com/en-us/windows/win32/seccng/cng-portal) for cryptographic operations.
On Windows, the Microsoft build of Go uses the [CNG library (Cryptography API: Next Generation)](https://learn.microsoft.com/en-us/windows/win32/seccng/cng-portal) for cryptographic operations.
CNG is available since Windows Vista and Windows Server 2008 and it doesn't require any additional installation nor configuration.

### Linux

On Linux, Microsoft Go uses the [OpenSSL crypto library](https://docs.openssl.org/3.0/man7/crypto/) for cryptographic operations.
On Linux, the Microsoft build of Go uses the [OpenSSL crypto library](https://docs.openssl.org/3.0/man7/crypto/) for cryptographic operations.
OpenSSL is normally available on Linux distributions, but it may not be installed by default.
If it is not installed, you can install it using the package manager of your distribution.

OpenSSL 3 implements all the cryptographic algorithms using [Providers](https://docs.openssl.org/3.0/man7/crypto/#providers).
Microsoft Go officially supports the built-in providers and [SCOSSL (SymCrypt provider for OpenSSL)](https://github.com/microsoft/SymCrypt-OpenSSL) v1.6.1 or later.
The Microsoft build of Go officially supports the built-in providers and [SCOSSL (SymCrypt provider for OpenSSL)](https://github.com/microsoft/SymCrypt-OpenSSL) v1.6.1 or later.
SCOSSL is expected to be used with the default built-in provider enabled as a fallback (which is the case when using [Azure Linux 3](https://github.com/microsoft/AzureLinux)).

## macOS

On macOS, Microsoft Go uses [CommonCrypto](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/Common%20Crypto.3cc.html) and [CryptoKit](https://developer.apple.com/documentation/cryptokit) for cryptographic operations.
On macOS, th Microsoft build Go uses [CommonCrypto](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/Common%20Crypto.3cc.html) and [CryptoKit](https://developer.apple.com/documentation/cryptokit) for cryptographic operations.
CommonCrypto and CryptoKit are shipped with macOS and don't require any additional installation nor configuration.
Currently macOS 13 and above is supported.

Expand All @@ -42,7 +42,7 @@ The following legend describes the symbols used in the tables to indicate the le
| ⚠️ | Supported with limitations that require special configuration action |
|| Not supported |

When an algorithm is not supported or the limitations are exceeded, Microsoft Go will fall back to the Go implementation.
When an algorithm is not supported or the limitations are exceeded, the Microsoft build of Go will fall back to the Go implementation.

## Hash and Message Authentication Algorithms

Expand Down Expand Up @@ -75,7 +75,7 @@ This section includes the following packages:
| CSHAKE-256 ||||
| HMAC<sup>3</sup> | ✔️ | ✔️ | ✔️ |

<sup>1</sup>Available starting in Microsoft Go 1.24.
<sup>1</sup>Available starting in the Microsoft build of Go 1.24.

<sup>2</sup>Requires OpenSSL 1.1.1 or later.

Expand Down Expand Up @@ -167,7 +167,7 @@ Operations that require random numbers (rand io.Reader) only support [rand.Reade

<sup>1</sup>Supports only hash algorithms that are [supported as standalone hash functions](#hash-and-message-authentication-algorithms).

<sup>2</sup>Available starting in Microsoft Go 1.24.
<sup>2</sup>Available starting in the Microsoft build of Go 1.24.

<sup>3</sup>On Windows, when verifying a PSS signature, [rsa.PSSSaltLengthAuto](https://pkg.go.dev/crypto/rsa#pkg-constants) is not supported.

Expand Down
12 changes: 6 additions & 6 deletions eng/doc/DeveloperGuide.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Developer Guide

This document is a guide for developers who want to contribute to the Microsoft Go repository.
This document is a guide for developers who want to contribute to the Microsoft build of Go repository.
It explains how to build the repository, how to work with the Go submodule, and how to use the different tools that help maintain the repository.

This guide is primarily intended for developers working for the Go team at Microsoft, but it can also be useful for external contributors.
Expand All @@ -15,21 +15,21 @@ For details, visit https://cla.opensource.microsoft.com.
### Install a Go toolchain

A preexisting Go toolchain is required to bootstrap the build process.
You can use your system's package manager to install Go, download Go from the [official Go website](https://golang.org/dl/), or download a prebuilt version of Microsoft Go itself.
You can use your system's package manager to install Go, download Go from the [official Go website](https://golang.org/dl/), or download a prebuilt version of the Microsoft build Go itself.

The only requirement is that the Go version is high enough for the bootstrap process.
If you attempt to build Go while using a bootstrap Go with a version that is too low, the bootstrap process will fail and ask you to install a newer version.

> [!NOTE]
> The in-support versions of Go found on the [official Go website](https://golang.org/dl/) are always high enough to bootstrap the development branch.
> This is because:
> * The [last two major versions of Go are supported by the Go project](https://go.dev/s/release#release-maintenance). (Microsoft Go has the same policy.)
> * The [last two major versions of Go are supported by the Go project](https://go.dev/s/release#release-maintenance). (the Microsoft build of Go has the same policy.)
> * Go N can always be bootstrapped by [both N-1 and N-2](https://tip.golang.org/doc/install/source#go14).
> [!NOTE]
> This repository's `eng/run.ps1` PowerShell script is able to download a correct bootstrapping Go version automatically before building Microsoft Go from source.
> We recommend that Microsoft Go team members be familiar with this script because it is used by Microsoft Go CI.
> However, it isn't necessary to use the script for most work on the Microsoft Go patches.
> This repository's `eng/run.ps1` PowerShell script is able to download a correct bootstrapping Go version automatically before building the Microsoft build of Go from source.
> We recommend that Microsoft developers team members be familiar with this script because it is used by our CI.
> However, it isn't necessary to use the script for most work on the Microsoft build of Go patches.
> See the [`eng` Readme](/eng/README.md) for more information about `eng/run.ps1`.
### Install git and the git-go-patch command
Expand Down
Loading

0 comments on commit 4ee4caa

Please sign in to comment.