Skip to content

DEVELOPMENT.adoc

Latest commit

 

History

History
126 lines (101 loc) · 5.95 KB

DEVELOPMENT.adoc

File metadata and controls

126 lines (101 loc) · 5.95 KB

Development

Setup

  1. (mandatory) Install a JDK (JDK 21+ required).

  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 you 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 uses specific JDK versions in certain subdirectories. Pkl comes with a .java-version file specifying JDK 21.
    Enable jenv plugins for better handling by gradle:

    jenv enable-plugin gradle
jenv enable-plugin export

  6. (optional) If you’ve named the original apple/pkl git repository something other than origin, set env var PKL_ORIGINAL_REMOTE_NAME to that name in your .bashrc, .zshrc, config.fish or however you manage your local environment.

    This will allow spotless to pick the correct starting branch when formatting source code files. Otherwise, you might see that every file has its copyright year updated.

Additional Linux Setup

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

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 spotlessApply        # fix code formatting
gw build                # build everything except native executables
gw pkl-cli:testNative   # run native executable tests
gw pkl-cli:buildNative  # build native executable for current platform

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. Validate changes with gw build buildNative

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/

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

Snippet Test Plugin

There is an IntelliJ plugin meant for development on the Pkl project itself located in pkl-project-commons.

See its readme for instructions on how to set it up.