Skip to content

Latest commit

 

History

History
121 lines (99 loc) · 5.36 KB

DEVELOPMENT.adoc

File metadata and controls

121 lines (99 loc) · 5.36 KB
Raw

Development

Setup

  1. (mandatory) Install a JDK (any version between 17 - 21).

  2. (recommended) Install IntelliJ IDEA
    To import the project into IntelliJ, go to File→Open and select the project’s root directory. If the project is opened but not imported, look for a popup in the lower right corner and click its "Import Gradle Project" link.

  3. (recommended) Install gng
    gng enables to run Gradle commands with gw (instead of ./gradlew) from any subdirectory.

  4. (recommended) Set up Git ignore-revs
    git config blame.ignoreRevsFile .git-blame-ignore-revs

  5. (recommended) Install jenv and plugins
    jenv use specific JDK versions in certain subdirectories. Pkl comes with a .java-version file specifying JDK 17.
    Enable jenv plugins for better handling by gradle:

    jenv enable-plugin gradle
jenv enable-plugin export

Additional Windows Setup

  1. (optional) Go to System→For developers and enable Developer Mode. Otherwise, some tests may fail due to insufficient file system privileges.

  2. (optional) To build the native executable (./gradlew buildNative), install Prerequisites For Native Image on Windows.

Common Build Commands

gw clean
gw test          # run all tests except native executable tests
gw testNative    # run native executable tests
gw spotlessApply # fix code formatting
gw build         # build everything except native executables
gw buildNative   # build native executable(s) for current platform
                 # (Alpine executable is only built if ~/staticdeps/bin/musl-gcc exists)

pkl-cli/build/executable/jpkl                   # run Java executable
pkl-cli/build/executable/pkl-macos-aarch64      # run Mac executable
pkl-cli/build/executable/pkl-macos-amd64        # run Intel Mac executable
pkl-cli/build/executable/pkl-linux-amd64        # run Linux executable
pkl-cli/build/executable/pkl-alpine-linux-amd64 # run Alpine Linux executable
pkl-cli/build/executable/pkl-windows-amd64.exe  # run Windows executable

Update Gradle

  1. Go to https://gradle.org/release-checksums/ and copy the checksum for the new Gradle version

  2. Run the following command twice (until it prints UP-TO-DATE):

    gw wrapper --gradle-version [version] --gradle-distribution-sha256-sum [sha]

  3. Commit the updated wrapper files

Update Dependencies

  1. (optional) Update gradle/libs.version.toml based on version information from https://search.maven.org, https://plugins.gradle.org, and GitHub repos

  2. Run gw updateDependencyLocks

  3. Validate changes with gw build buildNative

  4. Review and commit the updated dependency lock files

Code Generation

  • Truffle code generation is performed by Truffle’s annotation processor, which runs as part of task :pkl-core:compileJava

    • Output dir is generated/truffle/

  • ANTLR code generation is performed by task :pkl-core:generateGrammarSource

    • Output dir is generated/antlr/

Remote JVM Debugging

To enable remote JVM debugging when running Gradle tasks (e.g. test), add the flag -Djvmdebug=true. This will listen on port 5005.

Example: ./gradlew test -Djvmdebug=true