Update ChakraCore build instructions for ICU #51
Conversation
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
dilijev
reviewed
Apr 14, 2018
| @@ -47,23 +47,27 @@ msbuild ... /p:RuntimeLib=static_library ... | |||
|
|
|||
| ### Windows + ICU (Experimental) ### | |||
|
|
|||
| ChakraCore on Windows has experimental integration with ICU on x64. This can be turned on using either a custom build of ICU that we call Chakra.ICU, or by providing your own build of ICU. | |||
| ChakraCore on Windows has experimental integration with ICU on x86 and x64. You can choose to download and compile ICU using our helper scripts, provide your own ICU installation, or use the ICU SDK installed alongside the version 16299 or later of the Windows Kit. For any of these options, you will need to provide the `ChakraICU` parameter to `msbuild`, either on the command line (`/p:ChakraICU=value`) or through an environment variable (`set ChakraICU=value`). The possible values are discussed below. | |||
There was a problem hiding this comment.
alongside the version 16299 -> alongside version 16299
There was a problem hiding this comment.
nit: I prefer breaking up sentences, clauses, etc., to one line each in markdown because it is rendered the same and makes leaving review comments and, later, seeing diffs, easier.
|
|
||
| To get started with Chakra.ICU, run `python tools\configure_icu.py <version>` from the ChakraCore root directory, where `<version>` is a version of ICU, like 57.1 or 60.2. You can run `python tools\configure_icu.py --help` to see all available configuration options. Running this script will download ICU to `%ChakraCoreRootDirectory%\deps\Chakra.ICU\icu` (by default) and will generate `%ChakraCoreRootDirectory%\deps\Chakra.ICU\Chakra.ICU.props`, which contains all of the files and source information for the given version of ICU in a MSBuild-compatible format. | ||
|
|
||
| To actually build ChakraCore with Chakra.ICU, you need to pass the ChakraICU parameter, either through the command line (`msbuild ... /p:ChakraICU=<value>`) or through an environment variable (`set ChakraICU=<value>`). The supported values are `static` and `shared`; `static` links ICU statically into ChakraCore.dll, and `shared` creates `Chakra.ICU.Common.dll`, `Chakra.ICU.i18n.dll`, and `Chakra.ICU.Data.dll`. If you choose `shared`, you will need to redistribute the Chakra.ICU DLLs alongside ChakraCore.dll and the rest of your application. | ||
| To build the version of ICU that you just downloaded, you can set `ChakraICU` to `static` or `shared`; `static` links ICU statically into ChakraCore.dll, and `shared` creates `Chakra.ICU.Common.dll`, `Chakra.ICU.i18n.dll`, and `Chakra.ICU.Data.dll`. If you choose `shared`, you will need to redistribute the Chakra.ICU DLLs alongside ChakraCore.dll and the rest of your application. |
There was a problem hiding this comment.
Chakra.ICU.*.dll might be clearer.
nit: wrap filenames in backticks (Chakra.ICU, ChakraCore.dll)
| #### Bring your own ICU #### | ||
| #### Using the ICU SDK included with the Windows Kit #### | ||
|
|
||
| **Warning**: By enabling this option, you are limiting the range of operating systems that the produced ChakraCore.dll can run on. Normally, ChakraCore.dll can be redistributed back to Windows 7 machines with no modifications. When you enable Windows Kit ICU, the resulting ChakraCore.dll will only be able to run on Windows 10 version 15063 (RS2) or later. |
There was a problem hiding this comment.
Let's assume not all developers know the meaning of the codename RS2 is and give the yymm number and marketing name of that release ("Creator's Update", I think?)
1703 | Redstone 2 | Creators Update | April 5, 2017 | October 9, 2018 | April 9, 2019 | N/A | July 11, 2019 | 15063 | 15063
Source https://en.wikipedia.org/wiki/Windows_10_version_history
|
|
||
| _note_: If you find yourself in the extremely niche position of wanting to use the ICU installed with the Windows Kit (as the Chakra team does internally), you will need to modify build files as that is not presently supported by the ChakraCore build system. By default, using the ICU included with the Windows Kit means that the resulting build of ChakraCore will only run on Windows 10 RS2 (build 15063) or later. If you want the resulting build of ChakraCore to run on older versions of Windows, you will need to build Chakra.ICU in the `shared` configuration and then copy those DLLs, as described in PR [4737](https://github.com/Microsoft/ChakraCore/pull/4737). | ||
| Chakra also supports bringing your own ICU, in case you are already using it elsewhere in your application. To use this configuration, set `ChakraICU` to `external`, and pass `IcuVersionMajor=<number>`, `IcuIncludeDirectories=<folder(s)>`, and `IcuLibraryDependencies=<libs>` to MSBuild using either the command line or environment variable methods described above. The directory/directories passed to `IcuIncludeDirectories` must have all of the icuuc and icuin headers located within a `unicode` subfolder -- that is, if you pass `C:\ICU\`, then it is expected that headers like `uloc.h`, `udat.h`, etc are located in `C:\ICU\unicode\`. |
There was a problem hiding this comment.
nit: wrap icuuc and icuin in backticks
dilijev
approved these changes
Apr 14, 2018
|
@jackhorton Is this ready to land? |
|
I should go over it once more and make sure it is, and then ill merge it this weekend. |
|
@jackhorton ping |
1 similar comment
|
@jackhorton ping |
liminzhu
reviewed
Sep 4, 2018
| #### Bring your own ICU #### | ||
| #### Using the ICU SDK included with the Windows Kit #### | ||
|
|
||
| **Warning**: By enabling this option, you are limiting the range of operating systems that the produced ChakraCore.dll can run on. Normally, ChakraCore.dll can be redistributed back to Windows 7 machines with no modifications. When you enable Windows Kit ICU, the resulting ChakraCore.dll will only be able to run on Windows 10 version 15063 (RS2) or later. |
There was a problem hiding this comment.
The warning part is a little redundant. I'd just say
On Windows 10 Creators Update (build 15063) later, ICU is included in the Windows Kit. To instruct ChakraCore to use the Windows Kit ICU, set ChakraICU to windows.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.