diff --git a/docs/devsetup/java/eclipse-setup-for-java-developers/index.md b/docs/devsetup/java/eclipse-setup-for-java-developers/index.md index 3bb6d5dd3766..d6aa6cf63402 100644 --- a/docs/devsetup/java/eclipse-setup-for-java-developers/index.md +++ b/docs/devsetup/java/eclipse-setup-for-java-developers/index.md @@ -10,7 +10,7 @@ parent: Java Setup License & terms of use: http://www.unicode.org/copyright.html --> -# Eclipse Setup for Java Developers +# Eclipse Setup for Java Developers Using Ant {: .no_toc } ## Contents @@ -33,8 +33,8 @@ ICU4J. If you don't do the following, you run the risk of calling Java library APIs that are newer than ICU4J's Java version, and you cause runtime exceptions for people who use the older version. -Currently (as of 2018-aug / ICU 63), ICU4J is on Java 7 (and Eclipse 4.6 -requires Java 8). +Currently (as of 2023-sep / ICU 73), ICU4J is on Java 8 (and Eclipse 4.28/2023-06 +requires Java 17). (Note: localespi/localespi-tests may use a different Java version from ICU4J proper.) @@ -46,8 +46,8 @@ proper.) 2. Select \[Window\] - \[Preferences\] *(On Mac, this is \[Eclipse - Preferences\])* 3. Navigate the preferences tree to Java/Installed JREs/Execution Environments -4. On the left, Execution Enviornments: Select J2SE-1.7 -5. On the right, Compatible JREs, if there is no old-version Java 7 JRE: +4. On the left, Execution Enviornments: Select J2SE-1.8 +5. On the right, Compatible JREs, if there is no old-version Java 8 JRE: 1. Go up one tree level to Java/Installed JREs. 2. Click "Add..." and select "Standard VM" as JRE type. 3. Click "Directory..." and find the location of your old-version JRE (or @@ -59,7 +59,7 @@ proper.) 5. Go back down in the tree to Java/Installed JREs/Execution Environments. 6. On the right, Compatible JREs, you should now see your old-version JRE 6. The matching-old-version JRE should have a "\[perfect match\]" suffix. - Select it for "JavaSE-1.7" on the left. + Select it for "JavaSE-1.8" on the left. ## Other Settings diff --git a/docs/devsetup/java/maven.md b/docs/devsetup/java/maven.md new file mode 100644 index 000000000000..4d847611a2bf --- /dev/null +++ b/docs/devsetup/java/maven.md @@ -0,0 +1,236 @@ +--- +layout: default +title: Maven Setup for Java +grand_parent: Setup for Contributors +parent: Java Setup +--- + + + +# Maven Setup for Java +{: .no_toc } + +## Contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +--- + + +Maven is a standard build tool in the Java ecosystem with a very well-defined +preferred way to organize the directory structure and execute builds. +Thus, many IDEs for Java will have some level of support for Maven. +The command line invocation is still, of course, the standard of truth for the build. + +## Installation + +Install Maven from your OS package manager. +The minimum version is 3.2.5 as of ICU 74, +although this may change. +See the `/icu4j/pom.xml` root POM file's maven-enforcer-plugin +for the current minimum version. +The Maven page lists [system requirements](https://maven.apache.org/download.cgi), +which includes a minimum of JDK 8 as of ICU 74. + +## IDE Setup + +Users of IDEs should familiarize themselves with the information about how to use Maven at +the command line, +which also includes information about Maven builds. + +> :point_right: **Note**: In most IDEs, whenever the Maven configurations change (`pom.xml` files), +you will need to refresh your IDE project using the IDE's Maven plugin/functionality. + +Most IDEs represent user settings for different codebases via an IDE-specific notion +usually called "project" or "workspace". +The IDE's project/workspace is a separate construct from the Maven configurations for the codebase. +Therefore, creating a new project for an existing codebase is done by "importing" the codebase, +in which the IDE creates the project/workspace settings files. +If you pull updates to the upstream ICU codebase codebase that result in changes to Maven settings, +then the IDE behavior may be behind until you update your IDE project accordingly. + + +### IntelliJ + +IntelliJ does a good job of understanding multi-module Maven projects, +including the non-standard configuration here. +It also recognizes the customized locations of source code files and test code files in the configuration here. + +To import into IntelliJ: + +1. In IntelliJ, open a new project. + a. Recent versions of IntelliJ provide a dialog box on startup to select a project. Click the "Open" button.) +2. Select the root `pom.xml` in ICU4J (ex: `/icu4j/pom.xml`) +3. That's it. Note: IntelliJ will take a few minutes to do a one-time indexing of the new source code. + +Navigating the source code files between main code and test code, and running tests individually or for an entire module, +work as they do normally in IntelliJ. + +> :point_right: **Note**: Currently, Maven cannot build the entire project due to settings for `tools/utilities-for-cldr`. To work around this so that `Build > Build Project` works: in the "Project" toolbar, navigate to the `tools/utilities-for-cldr` folder, right click for the contextual menu, then `Maven > Ignore Projects`. +> +> When this workaround is no longer needed, the project can be reenabled by: `View > Tool Windows > Maven`, then expand "International Components for Unicode (ICU)", right click on `utilities-for-cldr`, then select `Unignore Projects`. + +### Eclipse + +[Eclipse's Maven plugin](https://eclipse.dev/m2e/) +works reasonably well and can support the import of a multi-module Maven project. +These instructions have not yet verified Eclipse's handling of the import of the ICU4J using a Maven build. + +### VS Code + +VS Code's support of Maven projects is not as robust as IntelliJ's when it comes to the non-standard file layout for sources and tests. +The Maven support comes from the standard Java extension (which depends on the standard Maven extension) from the extension marketplace. +Source and test code files are not recognized properly, and it is not clear how to execute the tests. + +However, a workaround exists for those who want to use VS Code as their preferred editor and still execute commands to recompile or run tests. +The workaround relies on invoking the Maven commands in a shell, and using a VS Code extension to create shortcuts within the IDE to invoke those commands. + +The extension is [Command Runner](https://marketplace.visualstudio.com/items?itemName=edonet.vscode-command-runner). +Next, create a VS Code workspace (File > Open Folder...) at the ICU4J root at `/icu4j`. +Then edit your settings for your VS Code workspace for ICU4J (this is the file at `/icu4j/.vscode/settings.json`) +by adding this section to the settings: + +```jsonnet +{ + //... + "command-runner.commands": { + // The following commands assume your VS Code workspace is rooted at `/icu4j`. If not, + // then adjust accordingly. + "core > all > compile": "cd ${workspaceFolder}; mvn -am -pl main/core compile", + "core > all > test": "cd ${workspaceFolder}; mvn -am -pl main/core test -Dsurefire.failIfNoSpecifiedTests=false", + "core > number > test": "cd ${workspaceFolder}; mvn -am -pl main/core test -Dtest=\"com/ibm/icu/dev/test/number/*,com/ibm/icu/dev/impl/number/*\" -Dsurefire.failIfNoSpecifiedTests=false", + "core > text > test": "cd ${workspaceFolder}; mvn -am -pl main/core test -Dtest=\"com.ibm.icu.dev.test.text.*\" -Dsurefire.failIfNoSpecifiedTests=false", + "charset > compile": "cd ${workspaceFolder}; mvn -am -pl main/charset compile", + "charset > test": "cd ${workspaceFolder}; mvn -am -pl main/charset test -Dsurefire.failIfNoSpecifiedTests=false", + "localespi > compile": "cd ${workspaceFolder}; mvn -am -pl main/localespi compile", + "localespi > test": "cd ${workspaceFolder}; mvn -am -pl main/localespi test -Dsurefire.failIfNoSpecifiedTests=false", + } + //... +} +``` + +As the extension's documentation describes, there are multiple ways to open up the palette of command shortcuts. +One way is to hit Ctrl/Cmd+Shift+P, then type "Run Command", then hit enter. +Another way is to right-click the background of any editor pane. + +After the palette appears, you can choose which Maven build target to execute. + +## Usage at the command line + +Maven divides its concept of a build into a "lifecycle" of a linear sequence of steps, called "phases". +These phases have a predefined order, and each phase can only begin if all of the previous phases have finished successfully. +Phases also serve as default build targets. +The sequence of phases include ... `compile` ... `test` ... `package` ... `integration-test` ... `verify` ... `deploy`. + +### Compile + +At the root of the project, you can run `mvn compile` to build/compile, and `mvn test` to run all of the tests (after first compiling successfully). + +### Testing + +To only execute a command within a submodule of the project, from the root, use the `-am -pl ` syntax like this: + +``` +mvn test -am -pl main/core +``` + +The `test` target runs unit tests only, while `integraiton-test` runs unit tests *and* integration tests. + +where `` is a comma-separated list of names of the subfolders which contain the submodule configuration pom.xml files. + +If you want to run only a specific test(s), use the `-Dtest=""` option, where `` can be a test name, a class name / package prefix, or a comma-separate list of them. + + +#### Run unit tests + +The `test` target will only run unit tests (excludes integration tests). Ex: + +``` +mvn test -am -pl main/core +``` + +#### Run all tests (integration and unit tests) + +The `integration-test` target will run integration tests *and* unit tests. Ex: + +``` +mvn integration-test -am -pl main/core +``` + +#### Run a single test +``` +mvn test -Dtest="ULocaleTest" -Dsurefire.failIfNoSpecifiedTests=false +``` +or +``` +mvn test -Dtest="com.ibm.icu.dev.test.util.ULocaleTest" -Dsurefire.failIfNoSpecifiedTests=false +``` + +#### Run a single method in a single test + +``` +mvn test -Dtest="ULocaleTest#TestGetAvailableByType" -Dsurefire.failIfNoSpecifiedTests=false +``` + +#### Run multiple tests +You can use regular expression patterns and comma-separate lists, +such as: + +``` +mvn test -Dtest="RBBI*" -Dsurefire.failIfNoSpecifiedTests=false +mvn test -Dtest="*Locale*" -Dsurefire.failIfNoSpecifiedTests=false +``` + +or + +``` +mvn test -Dtest="*Locale*,RBBI*" -Dsurefire.failIfNoSpecifiedTests=false +``` + +If you want to run tests according to the package structure of the classes, +then you should use the filesystem notation for the test files in the regular expression expansion. +Therefore, this syntax will not work: `mvn test -Dtest="com.ibm.icu.dev.test.util.*" -Dsurefire.failIfNoSpecifiedTests=false`. Instead, you want to use this syntax: +``` +mvn test -Dtest="com/ibm/icu/dev/test/util/*" -Dsurefire.failIfNoSpecifiedTests=false +``` + +#### Run in exhaustive mode + +Some tests in ICU are configured to run only when "exhaustive mode" is enabled. +Exhaustive mode enables long running tests that would otherwise not run, +or would run far fewer iterations. +Exhaustive mode is configured through the system property `ICU.exhaustive`. +`ICU.exhaustive` takes an integer value from 0 to 10 such that, +when greater than 5, +will trigger some tests to run in exhaustive mode. +See `TestFmwk.java` for more details, +and `ExhaustiveNumberTest.java` for an example of a test using it. + +``` +mvn integration-test -DICU.exhaustive=10 +``` + +#### Skip tests + +If you want to skip tests, add the options: + +``` +-DskipTests -DskipITs +``` + +The first option specifies skipping unit tests, +and the second option specifies skipping integration tests. + + +## More info on Maven + +To learn more about the details of Maven not covered above, +start by reading the [*Maven by Example* book](https://books.sonatype.com/mvnex-book/reference/index.html), +which gives an overview of Maven. +For more details on a specific topic, +refer to the [*Maven: Complete Reference* book](https://books.sonatype.com/mvnref-book/reference/index.html). \ No newline at end of file diff --git a/docs/userguide/icu4j/index.md b/docs/userguide/icu4j/index.md index d38309c17e76..7f47cda1f8a1 100644 --- a/docs/userguide/icu4j/index.md +++ b/docs/userguide/icu4j/index.md @@ -55,9 +55,8 @@ ICU4J is an add-on to the regular JRE that provides: ## Platform Dependencies -The minimum Java runtime version supported by ICU4J 68 is version 7\. Java runtime version 6 is not supported. - -ICU4J since version 63 depend on J2SE 7 functionality. Therefore, ICU4J only runs on JRE version 7 or later. ICU4J 68 is tested on JRE 7, 8, 9, 10 and 11. +Check the [Downloading ICU](https://icu.unicode.org/download) page to look up the minimum supported version of Java +for your version of ICU. ## How to Download ICU4J @@ -68,32 +67,33 @@ There are a few different ways to download the ICU4J releases. * [ICU Download page](https://icu.unicode.org/download) * Maven repository: -~~~ - - com.ibm.icu - icu4j - 68.1 - - - - com.ibm.icu - icu4j-charset - 68.1 - - - - com.ibm.icu - icu4j-localespi - 68.1 - -~~~ + ``` + + com.ibm.icu + icu4j + 68.1 + + + + com.ibm.icu + icu4j-charset + 68.1 + + + + com.ibm.icu + icu4j-localespi + 68.1 + + ``` * **GitHub Source Repository:** - If you are interested in developing features, patches, or bug fixes for ICU4J, you should probably be working with the latest version of the ICU4J source code. You will need to clone and checkout the code from our GitHub repository to ensure that you have the most recent version of all of the files. There are several ways to do this. Please follow the directions that are contained on the [Source Repository page](https://icu.unicode.org/repository) for details. + If you are interested in developing features, patches, or bug fixes for ICU4J, you should probably be working with the latest version of the ICU4J source code. You will need to clone and checkout the code from our GitHub repository to ensure that you have the most recent version of all of the files. There are several ways to do this. Please follow the directions that are contained on the [Source Code Setup page](../../devsetup/source/) for details. For more details on how to download ICU4J directly from the web site, please see the ICU download page at [https://icu.unicode.org/download](https://icu.unicode.org/download) -## The Structure and Contents of ICU4J + +## The Structure and Contents of ICU4J - ICU 74 and later Below, all directory paths are relative to the directory where the ICU4J source archive is extracted. @@ -101,8 +101,84 @@ Below, all directory paths are relative to the directory where the ICU4J source | Path | Description | |------------------------------|-----------------------------------------------------------------------------------------| -| build.xml | The main Ant build file for ICU4J. See [How to Install and Build](#how-to-install-and-build) for more information | -| main/shared/licenses/LICENSE | ICU license | +| `pom.xml` | The root Maven build file for ICU4J. See [How to Install and Build](#how-to-install-and-build---icu-74-and-later) for more information | +| `LICENSE` | ICU license | + +### ICU4J runtime class files + +Each sub-component is represented in the Maven build as a separate Maven module / project. + +The directory structure of the codebase within each module follows Maven defaults. +Thus, runtime class sources will be in the `src/main/java` subdirectory of the module. +Ex: the class `com.ibm.icu.text.Collator` can be found at `/icu4j/main/collate/src/main/java/com/ibm/icu/text/Collator.java`. +Any resource files (non-source files) will be located at `src/main/resources`. + + +| Sub-component Path | Sub-component Name | Build Dependencies | Public API Packages | Description | +|-------------------------|--------------------|---------------------------|---------------------|---------------| +| `main/charset` | `icu4j-charset` | `icu4j-core` | `com.ibm.icu.charset` | Implementation of `java.nio.charset.spi.CharsetProvider`. This sub-component is shipped as `icu4j-charset.jar` along with ICU charset converter data files. | +| `main/collate` | `collate` | `core` | `com.ibm.icu.text`
`com.ibm.icu.util` | Collator APIs and implementation. Also includes some public API classes that depend on Collator. This sub-component is packaged as a part of `icu4j.jar`. | +| `main/core` | `core` | n/a | `com.ibm.icu.lang`
`com.ibm.icu.math`
`com.ibm.icu.text`
`com.ibm.icu.util` | ICU core API classes and implementation. This sub-component is packaged as a part of `icu4j.jar`. | +| `main/currdata` | `currdata` | `core` | n/a | No public API classes. Provides access to currency display data. This sub-component is packaged as a part of `icu4j.jar`. | +| `main/langdata` | `langdata` | `core` | n/a | No public API classes. Provides access to language display data. This sub-component is packaged as a part of `icu4j.jar`. | +| `main/localespi` | `icu4j-localespi` | `core`
`collate` | n/a | Implementation of various locale-sensitive service providers defined in `java.text.spi` and `java.util.spi` in J2SE 6.0 or later Java releases. This sub-component is shipped as `icu4j-localespi.jar`. | +| `main/regiondata` | `regiondata` | `core` | n/a | No public API classes. Provides access to region display data. This sub-component is packaged as a part of `icu4j.jar`. | +| `main/translit` | `translit` | `core` | `com.ibm.icu.text` | Transliterator APIs and implementation. This sub-component is packaged as a part of `icu4j.jar`. | + +### ICU4J unit test files + +Unit test and integration tests are grouped together in the same Maven submodule as the runtime class code +for the same component. +The test source code lives in the standard Maven directory structure, +`src/test/java` for test sources, +and `src/test/resources` for test-specific non-source files. + +> :point_right: **Note**: Tests that depend on multiple sub-components must be placed +in the `main/common_tests` directory and run as integration tests. + +The Maven build enforces isolation vis-a-vis dependencies for tests within a multi-module project such that +unit tests must only test code within its same submodule. +When a test depends on runtime code from multiple modules, it cannot exist in any of those modules, +or else it would create a circular dependency in the Maven build. +Instead, such tests should be refactored into a separate component +and designated as integration tests. + +| Path | Sub-component Name | Runtime Dependencies | Description | +|-------------------------------------------|---------------------------------|--------------------------------------------------------------------------------------------------------------|-------------------------------------------------| +| `main/common_tests` | `common_tests` | `core`
`currdata`
`translit`
`langdata`
`collate`
`regiondata`
| Sub-component for integration tests that depend on runtime code of multiple components. | + + +### Others + + + + + + + + + + + + + + + + + + +
PathDescription
demosICU4J demo programs.
perf-testsICU4J performance test files.
toolsICU4J tools including:
  • Custom JavaDoc taglets used for generating ICU4J API references.
  • API report tool and data.
  • Other independent utilities used for ICU4J development.
+ +## The Structure and Contents of ICU4J - ICU 73 and earlier + +Below, all directory paths are relative to the directory where the ICU4J source archive is extracted. + +### Information and build files + +| Path | Description | +|------------------------------|-----------------------------------------------------------------------------------------| +| `build.xml` | The main Ant build file for ICU4J. See [How to Install and Build](#how-to-install-and-build---icu-73-and-earlier) for more information | +| `main/shared/licenses/LICENSE` | ICU license | ### ICU4J runtime class files @@ -129,9 +205,6 @@ Below, all directory paths are relative to the directory where the ICU4J source | `main/tests/packaging` | `icu4j-packaging-tests` | `icu4j-core`
`icu4j-test-framework` | Test suite for sub-component packaging. | | `main/tests/translit` | `icu4j-translit-tests` | `icu4j-core`
`icu4j-translit`
`icu4j-test-framework` | Test suite for translit sub-component. | - - - ### Others @@ -161,6 +234,7 @@ Below, all directory paths are relative to the directory where the ICU4J source
+ ## Where to get Documentation The [ICU User Guide](../) contains lots of general information about ICU, in its C, C++, and Java incarnations. @@ -179,7 +253,91 @@ The complete API documentation for ICU4J (javadoc) is available on the ICU4J web * Unicode Text [Compression](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/UnicodeCompressor.html) & [Decompression](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/UnicodeDecompressor.html) – 2:1 compression on English Unicode text. * Collation – [Rule-based sorting](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/RuleBasedCollator.html), [Efficient multi-lingual searching](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/StringSearch.html), [Alphabetic indexing](https://unicode-org.github.io/icu-docs/apidoc/released/icu4j/com/ibm/icu/text/AlphabeticIndex.html) -## How to Install and Build +## How to Install and Build - ICU 74 and later + +Using a pre-built version of ICU from Maven Central can be achieved simply by using the artifact +coordinates as described above in the Maven portion of the [How to Download ICU4J](#how-to-download-icu4j) +section. + +For non Maven-aware builds, to install ICU4J, simply place the pre-built jar file `icu4j.jar` on your Java `CLASSPATH`. +If you need Charset API support please also place `icu4j-charset.jar` on your class path along with `icu4j.jar`. + +To build ICU4J, you will need a version of Maven and JDK supported by the version of ICU +and by the Maven build configuration. See [Maven Setup for Java](../../devsetup/java/maven). + +Once the JDK and Maven are installed, run the desired Maven target. For example: + +~~~ +~/icu/icu4j$ mvn verify +[INFO] Scanning for projects... +[INFO] ------------------------------------------------------------------------ +[INFO] Reactor Build Order: +[INFO] +[INFO] International Components for Unicode for Java (icu4j-root) [pom] +[INFO] framework [jar] +[INFO] core [jar] +[INFO] langdata [jar] +[INFO] regiondata [jar] +[INFO] currdata [jar] +[INFO] collate [jar] +[INFO] translit [jar] +[INFO] icu4j [jar] +[INFO] icu4j-charset [jar] +[INFO] common_tests [jar] +[INFO] icu4j-localespi [jar] +[INFO] demos [jar] +[INFO] samples [jar] +[INFO] tools_misc [jar] +[INFO] utilities-for-cldr [jar] +[INFO] perf-tests [jar] +[INFO] +[INFO] -----------------------< com.ibm.icu:icu4j-root >----------------------- +[INFO] Building International Components for Unicode for Java (icu4j-root) 74.1-SNAPSHOT [1/17] +[INFO] --------------------------------[ pom ]--------------------------------- +[INFO] +[INFO] --- maven-enforcer-plugin:3.3.0:enforce (enforce-maven) @ icu4j-root --- +[INFO] Rule 0: org.apache.maven.enforcer.rules.version.RequireMavenVersion passed +[INFO] + +... +... +... + +[INFO] Reactor Summary for International Components for Unicode for Java (icu4j-root) 74.1-SNAPSHOT: +[INFO] +[INFO] International Components for Unicode for Java (icu4j-root) SUCCESS [ 0.317 s] +[INFO] framework .......................................... SUCCESS [ 1.125 s] +[INFO] core ............................................... SUCCESS [02:28 min] +[INFO] langdata ........................................... SUCCESS [ 0.117 s] +[INFO] regiondata ......................................... SUCCESS [ 0.113 s] +[INFO] currdata ........................................... SUCCESS [ 0.113 s] +[INFO] collate ............................................ SUCCESS [ 32.421 s] +[INFO] translit ........................................... SUCCESS [ 27.787 s] +[INFO] icu4j .............................................. SUCCESS [ 0.019 s] +[INFO] icu4j-charset ...................................... SUCCESS [ 17.512 s] +[INFO] common_tests ....................................... SUCCESS [ 25.786 s] +[INFO] icu4j-localespi .................................... SUCCESS [ 0.202 s] +[INFO] demos .............................................. SUCCESS [ 0.111 s] +[INFO] samples ............................................ SUCCESS [ 0.076 s] +[INFO] tools_misc ......................................... SUCCESS [ 0.079 s] +[INFO] utilities-for-cldr ................................. SUCCESS [ 1.284 s] +[INFO] perf-tests ......................................... SUCCESS [ 0.128 s] +[INFO] ------------------------------------------------------------------------ +[INFO] BUILD SUCCESS +[INFO] ------------------------------------------------------------------------ +[INFO] Total time: 04:16 min +[INFO] Finished at: 2023-10-03T16:16:06-07:00 +[INFO] ------------------------------------------------------------------------ +~~~ + +> :point_right: **Note**: The above output is an example. The numbers are likely to be different with the current version ICU4J. + +For more information on how to build or test specific components, +or run specific tests, +or to set up your IDE, refer to +[Maven Setup for Java](../../devsetup/java/maven) + +## How to Install and Build - ICU 73 and earlier To install ICU4J, simply place the pre-built jar file `icu4j.jar` on your Java `CLASSPATH`. If you need Charset API support please also place `icu4j-charset.jar` on your class path along with `icu4j.jar`.