forked from dart-lang/sdk
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[wiki] move the https://github.com/dart-lang/sdk/wiki to the docs/ dir
Change-Id: I28db796fadcc111d97d3589bf3988ea0bbb8e18a Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/366682 Reviewed-by: Alexander Thomas <[email protected]> Commit-Queue: Devon Carew <[email protected]>
- Loading branch information
1 parent
3bdc1f9
commit 2837647
Showing
66 changed files
with
5,895 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,90 @@ | ||
| > [!IMPORTANT] | ||
| > This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. | ||
| > Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - | ||
| > removing this header - or send a CL to delete the file. | ||
| --- | ||
|
|
||
| Since Dart is an open-source project we rely on a number of other open-source projects, as tools | ||
| for building and testing, and as libraries compiled into the Dart SDK. Please follow these guidelines when working with third-party dependencies in both source and binary form. | ||
|
|
||
| # Third-party source dependencies | ||
|
|
||
| > [!IMPORTANT] | ||
| > New dependencies need explicit approval from Dart leadership before being added to the Dart SDK `DEPS` file unless they are [Dart core packages](https://pub.dev/publishers/dart.dev/packages) (Googlers see go/dart-sdk-deps-block for background information). To get approval, file an issue in the Dart SDK repo. | ||
| When adding new third party source dependencies please be very careful. Make sure that the license for the software is compatible with our license - a large set of licenses are more restrictive when you actually link in the source instead of just using the tools. | ||
| For example, a compiler's license might allow using it to compile our binary, but could be too restrictive to allow using its source code as part of the source code for a Dart SDK tool. | ||
| You must add a README.google if you check in third-party code, and note any local changes that have been applied to the code (see below for a template). Please cc [email protected] on any third-party additions. | ||
|
|
||
| If you need to discuss license issues to make sure that a license is compatible please reach out to the legal team at google or talk with [email protected] who can guide you to the right | ||
| person. Please refrain from speculating about licenses or make assumptions about what you may and may not do. If in doubt you should ask. If you are not a Google employee, contact a Dart team member who is. | ||
|
|
||
| We have a few rules to make sure that we can continue to build older versions of the SDK even if people delete or rewrite the history of repositories containing our third-party dependencies. There are two options for using repositories not hosted under https://github.com/dart-lang/ or https://github.com/google/: | ||
|
|
||
| 1. Move it to the dart-lang org, or fork it there. Moving is better than forking since it avoids fragmented versions. If you do fork, please state in the README that this is used for pulling in as a DEPS, don't make local changes, and be sure to not publish to pub from the dart-lang fork. | ||
|
|
||
| 2. Get the github repo mirrored on the dart.googlesource.com git server, and pull the dependency from there. This is the same way we do normal dependencies from dart-lang (see below), with one important exception: | ||
| **For security reasons, all code pulled in to build the Dart SDK must be reviewed by Google employees, no matter where it comes from.** This means that you, or a Google employee, need to do an initial review of all code up to and including the commit you put in the DEPS file for all external packages. | ||
|
|
||
| All external packages must be pinned to a fixed commit (revision) in the DEPS file. If you update the DEPS to pin a newer version, you need to do another review of the changes between the two revisions. You can upload the review (of the changes in the dependency, not just the change in the DEPS file) to https://dart-review.googlesource.com for easy reviewing, and upstream any fixes in this dependency, before pinning the new version of the dependency. | ||
|
|
||
| For all dependencies on GitHub, we need a mirror. File a GitHub issue labeled `area-infrastructure` (https://dartbug.com) requesting a mirror. The mirrors go to `https://dart.googlesource.com/external/github.com/<org>/<repo>.git`. Once the mirror is set up, you can commit your changes to the DEPS file pointing at the github mirror. | ||
|
|
||
| While you wait for the mirror to get set up, you can add the dependency to the DEPS file pointing directly to `http://github.com/<org>/<repo>.git`. This will let you develop against the dependency locally, but don't commit this. | ||
|
|
||
| # Rolling dependencies | ||
|
|
||
| Generally, in order to roll a dependency, you edit the SDK's [DEPS](https://github.com/dart-lang/sdk/blob/main/DEPS) file to reference the new commit for the particular package. You then run `gclient sync -D` to bring that commit into your local checkout, and follow the normal contribution process to contribute that change to the SDK (ala `git checkout -b roll_dep_foo; git add DEPS; git commit -m "[deps] update foo dep"; git cl upload`). | ||
|
|
||
| We also have two tools in the SDK that can help you roll deps: | ||
|
|
||
| ## Rolling a specific dependency | ||
|
|
||
| To roll a specific dependency, you can use the `tools/manage_deps.dart` script. From the SDK top level directory, run: | ||
|
|
||
| ``` | ||
| dart tools/manage_deps.dart bump third_party/pkg/package_config | ||
| ``` | ||
|
|
||
| That will update the DEPS file to the latest commit for the `package_config` dep and optionally create a CL for that change. | ||
|
|
||
| ## Rolling all package dependencies | ||
|
|
||
| In order to roll all Dart packages referenced in the DEPS file to their latest versions, run: | ||
|
|
||
| ``` | ||
| dart tools/rev_sdk_deps.dart | ||
| ``` | ||
|
|
||
| That will modify the DEPS file in-place, updating all the Dart packages deps to their latest versions. You can then create a CL of the changes via the normal contribution process. | ||
|
|
||
| # Third-party binaries and binary data in general | ||
|
|
||
| We occasionally need add binary versions of tools to make our testing/build/distribution infrastructure easier to maintain. These can be tools derived from our own source code (like fixed stable versions of the Dart standalone binary), or can be open source tools (like the standalone Firefox binary). Please be absolutely sure that the binary is compatible with our license. If your binary is not needed for building/distributing the core dart tool-chain you should consider other options (e.g., lazily fetching the files from the source or from Google Cloud Storage). In any case, always be vigilant about the license and please cc [email protected] on any third party additions. | ||
|
|
||
| # Where do they go | ||
|
|
||
| We put third party binaries on Google Cloud Storage and fetch them using a DEPS hook. We pin the DEPS entries to the hashes of specific versions, and we never delete old entries from the bucket where they are located, since that would destroy our ability to do old builds. This allows us to only have a single location holding the binaries for bleeding edge, dev branch, and stable releases. | ||
|
|
||
| Binary data is preferably added as a go/cipd package. Please note that only a select set of people have access to uploading CIPD package. If you feel that you need access or help please contact [email protected] | ||
|
|
||
| # README.google templates | ||
|
|
||
| When adding third party dependencies you must always add a README.google file describing what you put in, which license, which revision if applicable, the repository/page where you obtained the source/binary and any local modifications. You should also always make sure that there is a LICENSE file with the actual license. The following is a verbatim copy of the README.google for the firefox javascript shell, you can use that as a template. | ||
|
|
||
| ``` | ||
| Name: Firefox command line javascript shell. | ||
| Short Name: js-shell | ||
| URL: http://ftp.mozilla.org/pub/mozilla.org/firefox/candidates/15.0.1-candidates/build1/ | ||
| Version: 15.0.1 | ||
| Date: September 5th 2012 | ||
| License: MPL, http://www.mozilla.org/MPL | ||
| Description: | ||
| This directory contains the firefox js-shell binaries for Windows, Mac and | ||
| Linux. The files was fetched from: | ||
| http://ftp.mozilla.org/pub/mozilla.org/firefox/candidates/15.0.1-candidates/ | ||
| on September 28th 2012. | ||
| The binaries are used for testing dart code compiled to javascript. | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| > [!IMPORTANT] | ||
| > This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. | ||
| > Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - | ||
| > removing this header - or send a CL to delete the file. | ||
| --- | ||
|
|
||
| ## Branches and work flows | ||
|
|
||
| We have a rather simple branch setup for the dart project. Normally, everything is developed on the master branch. Features that are not yet ready for prime time are hidden under a flag, and enabled when sufficient stability has been proven. We occasionally create feature branches for landing big and disruptive changes. In addition to that, we have our dev, beta, and stable branches used for releasing the sdk. | ||
|
|
||
| In summary, we have in four main branches: | ||
|
|
||
| * **[master](https://github.com/dart-lang/sdk/blob/master/tools/VERSION)**: | ||
| Used for "everyday" development; land your CLs here. | ||
|
|
||
| * **[dev](https://github.com/dart-lang/sdk/blob/dev/tools/VERSION)**: | ||
| Populated from the master branch via full pushes, usually twice a week. Only in emergencies are [cherry picks](Cherry-picks-to-a-release-channel.md) landed on the dev channel. Don't land CLs here. Released via [dev channel builds](https://dart.dev/tools/sdk/archive#dev-channel). | ||
|
|
||
| * **[beta](https://github.com/dart-lang/sdk/blob/beta/tools/VERSION)**: | ||
| Populated from the dev branch via full pushes, usually once a month, or via [cherry picks](Cherry-picks-to-a-release-channel.md). Don't land CLs here. Released via [beta channel builds](https://dart.dev/tools/sdk/archive#beta-channel). | ||
|
|
||
| * **[stable](https://github.com/dart-lang/sdk/blob/stable/tools/VERSION)**: | ||
| Our main release branch, populated from the beta branch via full pushes when a release is ready, or via [cherry picks](Cherry-picks-to-a-release-channel.md). Don't land CLs here. Released via [stable channel builds](https://dart.dev/tools/sdk/archive#stable-channel). | ||
|
|
||
|
|
||
| ## Release cycle | ||
| Our normal release cycle is roughly 2 months long, but we don't make any guarantees, i.e., we may ship early if we feel that the stability is good or we may ship late if it is not. We don't normally follow a feature driven release cycle, but in some cases for larger changes to the language we may postpone a release to get all tools in sync. | ||
|
|
||
| During the entire cycle we do full merges of master to dev, basically releasing a green build from master on dev roughly twice a week. In case of bugs found quickly we do another full push. | ||
|
|
||
| We spend the last ~2 weeks of the cycle stabilizing the beta channel, starting with a full push of the latest dev release to beta. We only cherry picking critical fixes to the beta channel. People continue working on the master branch and dev releases will continue to be released. In this 2 week period we do multiple batches of cherry picks a week, and release those on the beta channel. We call this cherry-pick season. | ||
|
|
||
| Once we have something that looks good we merge it to stable and release it there. During the 2 months we do patch security, crash and critical bug releases on stable based on the latest stable version. | ||
|
|
||
| ### Getting your changes to beta channel during cherry pick season | ||
|
|
||
| See the [cherry pick to beta](Cherry-picks-to-a-release-channel.md) page for all the details on how to get a change cherry picked. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| > [!IMPORTANT] | ||
| > This page was copied from https://github.com/dart-lang/sdk/wiki and needs review. | ||
| > Please [contribute](../CONTRIBUTING.md) changes to bring it up-to-date - | ||
| > removing this header - or send a CL to delete the file. | ||
| --- | ||
|
|
||
| # Introduction | ||
|
|
||
| The Dart VM runs on a variety of ARM processors on Linux and Android. This document explains how to build the Dart VM and SDK to target these platforms. | ||
|
|
||
| # Cross-compiling | ||
|
|
||
| If you are building natively on the device you will be running on, you can skip this step. The build scripts download a cross-compilation toolchain using clang that supports ia32, x64, arm and arm64, so you do not need to install a cross-compiler yourself unless you want to target riscv. | ||
|
|
||
| ## Linux | ||
|
|
||
| If you are running Debian/Ubuntu, you can obtain a cross-compiler by doing the following: | ||
|
|
||
| ``` | ||
| $ sudo apt-get install g++-arm-linux-gnueabihf # For 32-bit ARM (ARMv7) | ||
| $ sudo apt-get install g++-aarch64-linux-gnu # For 64-bit ARM (ARMv8) | ||
| $ sudo apt-get install g++-riscv64-linux-gnu # For 64-bit RISC-V (RV64GC) | ||
| ``` | ||
|
|
||
| ## Android | ||
|
|
||
| Follow instructions under ["One-time Setup" under Android](Building-the-Dart-VM-for-Android) | ||
|
|
||
| # Building | ||
|
|
||
| ## Linux | ||
|
|
||
| With the default Debian/Ubuntu toolchains, simply do: | ||
|
|
||
| ``` | ||
| $ ./tools/build.py --no-rbe --no-clang --mode release --arch arm create_sdk | ||
| $ ./tools/build.py --no-rbe --no-clang --mode release --arch arm64 create_sdk | ||
| $ ./tools/build.py --no-rbe --no-clang --mode release --arch riscv64 create_sdk | ||
| ``` | ||
|
|
||
| You can also produce only a Dart VM runtime, no SDK, by replacing `create_sdk` with `runtime`. This process involves also building a VM that targets ia32/x64, which is used to generate a few parts of the SDK. | ||
|
|
||
| You can use a different toolchain using the -t switch. For example, if the path to your gcc is /path/to/toolchain/prefix-gcc, then you'd invoke the build script with: | ||
|
|
||
| ``` | ||
| $ ./tools/build.py --no-rbe --no-clang -m release -a arm -t arm=/path/to/toolchain/prefix create_sdk | ||
| $ ./tools/build.py --no-rbe --no-clang -m release -a arm64 -t arm64=/path/to/toolchain/prefix create_sdk | ||
| $ ./tools/build.py --no-rbe --no-clang -m release -a riscv32 -t riscv32=/path/to/toolchain/prefix create_sdk | ||
| $ ./tools/build.py --no-rbe --no-clang -m release -a riscv64 -t riscv64=/path/to/toolchain/prefix create_sdk | ||
| ``` | ||
|
|
||
| ## Android | ||
|
|
||
| The standalone Dart VM can also target Android. | ||
|
|
||
| ``` | ||
| $ ./tools/build.py --mode=release --arch=arm --os=android create_sdk | ||
| $ ./tools/build.py --mode=release --arch=arm64 --os=android create_sdk | ||
| $ ./tools/build.py --mode=release --arch=riscv64 --os=android create_sdk | ||
| ``` | ||
|
|
||
| For all of these configurations, the runtime only can be built using the runtime target as above. | ||
|
|
||
| ## Debian Packages | ||
|
|
||
| You can create Debian packages targeting ARM or RISC-V as follows: | ||
|
|
||
| ``` | ||
| $ ./tools/linux_dist_support/create_tarball.py | ||
| $ ./tools/linux_dist_support/create_debian_packages.py -a {ia32, x64, arm, arm64, riscv64} | ||
| ``` |
Oops, something went wrong.