|
2 | 2 |
|
3 | 3 | ## Generate SDK packages |
4 | 4 |
|
5 | | -### Generate an Azure-SDK-for-Go service package |
6 | | - |
7 | | -1. [Install AutoRest](https://github.com/Azure/autorest#installing-autorest). |
8 | | - |
9 | | -1. Call autorest with the following arguments... |
10 | | - |
11 | | -``` cmd |
12 | | -autorest path/to/readme/file --go --go-sdk-folder=<your/gopath/src/github.com/Azure/azure-sdk-for-go> --package-version=<version> --user-agent=<Azure-SDK-For-Go/version services> [--tag=choose/a/tag/in/the/readme/file] |
13 | | -``` |
14 | | - |
15 | | -For example... |
16 | | - |
17 | | -``` cmd |
18 | | -autorest C:/azure-rest-api-specs/specification/advisor/resource-manager/readme.md --go --go-sdk-folder=C:/goWorkspace/src/github.com/Azure/azure-sdk-for-go --tag=package-2016-07-preview --package-version=v11.2.0-beta --user-agent='Azure-SDK-For-Go/v11.2.0-beta services' |
19 | | -``` |
20 | | - |
21 | | -- If you are looking to generate code based on a specific swagger file, you can replace `path/to/readme/file` with `--input-file=path/to/swagger/file`. |
22 | | -- If the readme file you want to use as input does not have golang tags yet, you can call autorest like this... |
23 | | - |
24 | | -``` cmd |
25 | | -autorest path/to/readme/file --go --license-header=<MICROSOFT_APACHE_NO_VERSION> --namespace=<packageName> --output-folder=<your/gopath/src/github.com/Azure/azure-sdk-for-go/services/serviceName/mgmt/APIversion/packageName> --package-version=<version> --user-agent=<Azure-SDK-For-Go/version services> --clear-output-folder --can-clear-output-folder --tag=<choose/a/tag/in/the/readme/file> |
26 | | -``` |
27 | | - |
28 | | -For example... |
29 | | - |
30 | | -``` cmd |
31 | | -autorest --input-file=https://raw.githubusercontent.com/Azure/azure-rest-api-specs/current/specification/network/resource-manager/Microsoft.Network/2017-10-01/loadBalancer.json --go --license-header=MICROSOFT_APACHE_NO_VERSION --namespace=lb --output-folder=C:/goWorkspace/src/github.com/Azure/azure-sdk-for-go/services/network/mgmt/2017-09-01/network/lb --package-version=v11.2.0-beta --clear-output-folder --can-clear-output-folder |
32 | | -``` |
33 | | - |
34 | | -1. Run `go fmt` on the generated package folder. |
35 | | - |
36 | | -1. To make sure the SDK has been generated correctly, also run `golint`, `go build` and `go vet`. |
37 | | - |
38 | | -### Generate Azure SDK for Go service packages in bulk |
39 | | - |
40 | | -All services, all API versions. |
41 | | - |
42 | | -1. [Install AutoRest](https://github.com/Azure/autorest#installing-autorest). |
43 | | - |
44 | | -This repo contains a tool to generate the SDK, which depends on the golang tags from the readme files in the Azure REST API specs repo. The tool assumes you have an [Azure REST API specs](https://github.com/Azure/azure-rest-api-specs) clone, and [golint](https://github.com/golang/lint) is installed. |
45 | | - |
46 | | -1. `cd eng/tools/generator` |
47 | | - |
48 | | -1. `go install` |
49 | | - |
50 | | -1. Add `GOPATH/bin` to your `PATH`, in case it was not already there. |
51 | | - |
52 | | -1. Call the generator tool like this... |
53 | | - |
54 | | -``` cmd |
55 | | -generator –r [–v] [–l=logs/output/folder] –version=<version> path/to/your/swagger/repo/clone |
56 | | -``` |
57 | | - |
58 | | -For example... |
59 | | - |
60 | | -``` cmd |
61 | | -generator –r –v –l=temp –version=v11.2.0-beta C:/azure-rest-api-specs |
62 | | -``` |
63 | | - |
64 | | -The generator tool already runs `go fmt`, `golint`, `go build` and `go vet`; so running them is not necessary. |
65 | | - |
66 | | -#### Use the generator tool to generate a single package |
67 | | - |
68 | | -1. Just call the generator tool specifying the service to be generated in the input folder. |
69 | | - |
70 | | -``` cmd |
71 | | -generator –r [–v] [–l=logs/output/folder] –version=<version> path/to/your/swagger/repo/clone/specification/service |
72 | | -``` |
73 | | - |
74 | | -For example... |
75 | | - |
76 | | -``` cmd |
77 | | -generator –r –v –l=temp –version=v11.2.0-beta C:/azure-rest-api-specs/specification/network |
78 | | -``` |
79 | | - |
80 | | -## Include a new package in the SDK |
81 | | - |
82 | | -1. Submit a pull request to the Azure REST API specs repo adding the golang tags for the service and API versions in the service readme file, if the needed tags are not there yet. |
83 | | - |
84 | | -1. Once the tags are available in the Azure REST API specs repo, generate the SDK. |
85 | | - |
86 | | -1. In the changelog file, document the new generated SDK. Include the [autorest.go extension](https://github.com/Azure/autorest.go) version used, and the Azure REST API specs repo commit from where the SDK was generated. |
87 | | - |
88 | | -1. Install [dep](https://github.com/golang/dep). |
89 | | - |
90 | | -1. Run `dep ensure`. |
91 | | - |
92 | | -1. Submit a pull request to this repo, and we will review it. |
93 | | - |
94 | | -## Generate Azure SDK for Go profiles |
95 | | - |
96 | | -Take a look into the [profile generator documentation](https://github.com/Azure/azure-sdk-for-go/tree/main/eng/tools/profileBuilder) |
| 5 | +## Generate Go Mgmt SDK from Typespec |
| 6 | +### Prerequisites |
| 7 | +- [Node.js 18.x LTS](https://nodejs.org/en/download) or later |
| 8 | +- [Go 1.23.x](https://go.dev/doc/install) or later |
| 9 | +- [Git](https://git-scm.com/downloads) |
| 10 | +- Identify the `tspconfig.yaml` file for your package in the [Rest API Spec Repo](https://github.com/Azure/azure-rest-api-specs) and ensure there is a configuration for the Go SDK similar to that shown below and in [this example](https://github.com/Azure/azure-rest-api-specs/blob/main/specification/contosowidgetmanager/Contoso.Management/tspconfig.yaml#L40) |
| 11 | + |
| 12 | + ```yaml |
| 13 | + options: |
| 14 | + "@azure-tools/typespec-go": |
| 15 | + service-dir: "SERVICE_DIRECTORY_NAME" |
| 16 | + package-dir: "PACKAGE_DIRECTORY_NAME" # Should start with 'arm' following namespace review result. e.g. https://github.com/Azure/azure-sdk/issues/8290 |
| 17 | + module: "github.com/Azure/azure-sdk-for-go/{service-dir}/{package-dir}" |
| 18 | + fix-const-stuttering: true |
| 19 | + flavor: "azure" |
| 20 | + generate-examples: true |
| 21 | + generate-fakes: true |
| 22 | + head-as-boolean: true |
| 23 | + inject-spans: true |
| 24 | + ``` |
| 25 | +- Local Clone of Rest API Spec Repo Fork |
| 26 | + - If you don't already have a fork, [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) the [Rest API Spec Repo](https://github.com/Azure/azure-rest-api-specs). |
| 27 | + - Clone your fork of the repo. |
| 28 | +
|
| 29 | + ``` |
| 30 | + git clone https://github.com/{YOUR_GITHUB_USERNAME}/azure-rest-api-specs.git |
| 31 | + ``` |
| 32 | +- Local Clone of Go Language Repo Fork |
| 33 | + - If you don't already have a fork, [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) the [Go Repo](https://github.com/Azure/azure-sdk-for-go). |
| 34 | + - Clone your fork of the repo. |
| 35 | + |
| 36 | + ``` |
| 37 | + git clone https://github.com/{YOUR_GITHUB_USERNAME}/azure-sdk-for-go.git |
| 38 | + ``` |
| 39 | + |
| 40 | +### Steps |
| 41 | +1. Complete the prerequisites listed above |
| 42 | +2. Run [automation_init.sh](https://github.com/Azure/azure-sdk-for-go/blob/main/eng/scripts/automation_init.sh) |
| 43 | + |
| 44 | + ```sh |
| 45 | + cd "~/azure-sdk-for-go/eng/scripts" # navigate to the script directory |
| 46 | + ./automation_init.sh |
| 47 | + ``` |
| 48 | + > On windows you can use Git Bash to run the script. This script also installs the generator as a global tool. |
| 49 | +3. Create a local json file named `generatedInput.json` with content similar to that shown below |
| 50 | + |
| 51 | + ```json |
| 52 | + { |
| 53 | + "dryRun": false, |
| 54 | + "specFolder": "LOCAL_AZURE-REST-API-SPECS_REPO_ROOT", // e.g. "C:/git/azure-rest-api-specs" |
| 55 | + "headSha": "SHA_OF_AZURE-REST-API-SPECS_REPO", // use ' git rev-parse HEAD ' on the local azure-rest-api-specs repo root |
| 56 | + "repoHttpsUrl": "https://github.com/Azure/azure-rest-api-specs", |
| 57 | + "relatedTypeSpecProjectFolder": [ |
| 58 | + "specification/SERVICE_DIRECTORY_NAME/PACKAGE_DIRECTORY_NAME/" // e.g specification/contosowidgetmanager/Contoso.Management |
| 59 | + ] |
| 60 | + } |
| 61 | + ``` |
| 62 | +4. Run the [Generator](https://github.com/chidozieononiwu/azure-sdk-for-go/tree/main/eng/tools/generator) |
| 63 | + ```sh |
| 64 | + generator automation-v2 "PATH_TO_generatedInput.json" generateOutput.json |
| 65 | + ``` |
| 66 | + > generateOutput.json is a parameter for the name of the output file that will be created by the script. |
| 67 | + |
| 68 | +5. View information about the generated SDK in `generateOutput.json` |
| 69 | +6. Prepare your SDK for release. The necessary approvals, guidance for testing, documentation, and release pipelines is described in your release plan. More information about the Azure SDK Release Tool is [here](https://eng.ms/docs/products/azure-developer-experience/plan/release-plan) |
0 commit comments