Skip to content

docs: updated README with info about app.yml file format #102

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
quintesse merged 1 commit into from
Mar 31, 2026
Merged

docs: updated README with info about app.yml file format #102

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 178 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,13 +89,34 @@ to get the required dependencies to run the code.
_NB: We could have used `jpm copy` instead of `jpm install` to copy the dependencies but that would not have created
the `app.yml` file._

## Installation

For now the simplest way to install `jpm` is to use [JBang](https://www.jbang.dev/download/):

```shell
jbang app install jpm@codejive
```

But you can also simply download and unzip the [release package](https://github.com/codejive/java-jpm/releases/latest) and run the `bin/jpm` script.

## Dependencies

Dependencies are listed in the `dependencies` section of the `app.yml` file:

```yaml
dependencies:
com.github.lalyos:jfiglet: 0.0.9
info.picocli:picocli: 4.7.7
org.yaml:snakeyaml: '2.5'
```

## Actions

The `app.yml` file doesn't just track dependencies - it can also define custom actions that can be executed with the `jpm do` command or through convenient alias commands.

### Defining Actions

Actions are defined in the `actions` section of your `app.yml` file:
Actions are defined in the `actions` section of the `app.yml` file:

```yaml
dependencies:
Expand Down Expand Up @@ -163,16 +184,6 @@ NB2: These actions are just a very simple convenience feature. For a much more f

- [Just](https://github.com/casey/just) - Just a command runner

## Installation

For now the simplest way to install `jpm` is to use [JBang](https://www.jbang.dev/download/):

```shell
jbang app install jpm@codejive
```

But you can also simply download and unzip the [release package](https://github.com/codejive/java-jpm/releases/latest) and run the `bin/jpm` script.

## Usage

### Main Command
Expand All @@ -194,6 +205,30 @@ Commands:
exec Execute a shell command.
```

### Common options

These options are supported by all commands:

```
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
(default: value of JPM_CACHE environment variable;
whatever is set in Maven's settings.xml or
$HOME/.m2/repository
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository to use when resolving
artifacts. Can be preceded by a name and an equals
sign, e.g. -r myrepo=https://my.repo.com/maven2.
When needing to pass user and password you can set
JPM_REPO_<name>_USER and JPM_REPO_<name>_PASSWORD
environment variables.
-q, --quiet Don't output non-essential information
-v, --verbose Enable verbose output for debugging
```

### Commands

#### search (alias: s)
Expand All @@ -216,23 +251,6 @@ Options:
-m, --max=<max> Maximum number of results to return
-a, --appinfo=<appInfoFile>
App info file to use (default './app.yml')
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
(default: value of JPM_CACHE environment variable;
whatever is set in Maven's settings.xml or
$HOME/.m2/repository
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository to use when resolving
artifacts. Can be preceded by a name and an equals
sign, e.g. -r myrepo=https://my.repo.com/maven2.
When needing to pass user and password you can set
JPM_REPO_<name>_USER and JPM_REPO_<name>_PASSWORD
environment variables.
-q, --quiet Don't output non-essential information
-v, --verbose Enable verbose output for debugging

Example:
jpm search httpclient
Expand All @@ -254,23 +272,6 @@ Parameters:
Options:
-a, --appinfo=<appInfoFile>
App info file to use (default './app.yml')
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
(default: value of JPM_CACHE environment variable;
whatever is set in Maven's settings.xml or
$HOME/.m2/repository
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository to use when resolving
artifacts. Can be preceded by a name and an equals
sign, e.g. -r myrepo=https://my.repo.com/maven2.
When needing to pass user and password you can set
JPM_REPO_<name>_USER and JPM_REPO_<name>_PASSWORD
environment variables.
-q, --quiet Don't output non-essential information
-v, --verbose Enable verbose output for debugging

Example:
jpm install org.apache.httpcomponents:httpclient:4.5.14
Expand All @@ -295,23 +296,6 @@ Options:
the mentioned artifacts and their dependencies,
possibly removing other files present in the
directory
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
(default: value of JPM_CACHE environment variable;
whatever is set in Maven's settings.xml or
$HOME/.m2/repository
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository to use when resolving
artifacts. Can be preceded by a name and an equals
sign, e.g. -r myrepo=https://my.repo.com/maven2.
When needing to pass user and password you can set
JPM_REPO_<name>_USER and JPM_REPO_<name>_PASSWORD
environment variables.
-q, --quiet Don't output non-essential information
-v, --verbose Enable verbose output for debugging

Example:
jpm copy org.apache.httpcomponents:httpclient:4.5.14
Expand All @@ -333,22 +317,6 @@ Parameters:
Options:
-a, --appinfo=<appInfoFile>
App info file to use (default './app.yml')
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
(default: value of JPM_CACHE environment variable;
whatever is set in Maven's settings.xml or
$HOME/.m2/repository
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository to use when resolving
artifacts. Can be preceded by a name and an equals
sign, e.g. -r myrepo=https://my.repo.com/maven2.
When needing to pass user and password you can set
JPM_REPO_<name>_USER and JPM_REPO_<name>_PASSWORD
environment variables.
-v, --verbose Enable verbose output for debugging

Example:
jpm path org.apache.httpcomponents:httpclient:4.5.14
Expand All @@ -373,23 +341,6 @@ Options:
-l, --list List all available actions
-a, --appinfo=<appInfoFile>
App info file to use (default './app.yml')
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
(default: value of JPM_CACHE environment variable;
whatever is set in Maven's settings.xml or
$HOME/.m2/repository
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository to use when resolving
artifacts. Can be preceded by a name and an equals
sign, e.g. -r myrepo=https://my.repo.com/maven2.
When needing to pass user and password you can set
JPM_REPO_<name>_USER and JPM_REPO_<name>_PASSWORD
environment variables.
-q, --quiet Don't output non-essential information
-v, --verbose Enable verbose output for debugging

Example:
jpm do --list # List all actions
Expand All @@ -414,14 +365,6 @@ Parameters:
Options:
-a, --appinfo=<appInfoFile>
App info file to use (default './app.yml')
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository
-v, --verbose Enable verbose output for debugging

Example:
jpm build
Expand All @@ -443,15 +386,6 @@ Parameters:
Options:
-a, --appinfo=<appInfoFile>
App info file to use (default './app.yml')
-c, --cache=<cacheDir>
Directory where downloaded artifacts will be cached
-d, --directory=<directory>
Directory to copy artifacts to
-L, --no-links Always copy artifacts, don't try to create symlinks
-r, --repo=<repositories>
URL to additional repository
-q, --quiet Don't output non-essential information
-v, --verbose Enable verbose output for debugging

Supported tokens:
{{deps}} The classpath of all dependencies defined in app.yml
Expand All @@ -469,6 +403,138 @@ Example:
jpm exec @kotlinc -cp {{deps}} -d out/classes src/main/kotlin/App.kt
```

## app.yml File Format

The `app.yml` file is used by `jpm` to track project dependencies, define custom repositories, and configure actions for your Java project. This file makes it easy to share your project with others - they can simply run `jpm install` to get all required dependencies.

### File Structure

```yaml
name: MyApp
description: A sample Java application
documentation: https://github.com/user/myapp
java: 11+
authors:
- John Doe <john@example.com>
- Jane Smith <jane@example.com>
contributors:
- Bob Johnson <bob@example.com>

dependencies:
com.github.lalyos:jfiglet: 0.0.9
info.picocli:picocli: 4.7.7
org.yaml:snakeyaml: '2.5'

repositories:
myrepo: https://my.repo.com/maven2
private: https://private.repo.com/releases

actions:
setup: "echo Setting up the project..."
build: "javac -cp {{deps}} -d {./target/classes} src{/}*.java"
run: "java -cp {{deps}}{:}{./target/classes} Main"
test: "java -cp {{deps}}{:}{./target/classes} org.junit.runner.JUnitCore TestSuite"
clean: "rm -rf {./target}"
```

### Fields

#### Metadata Fields (Optional)

- **`name`** - The name of your application
- **`description`** - A brief description of what the application does
- **`documentation`** - URL to documentation or project homepage
- **`java`** - Minimum Java version required (e.g., `11`, `17`)
- **`authors`** - List of original authors with optional email addresses
- **`contributors`** - List of contributors with optional email addresses

#### dependencies (Required for most projects)

Lists the Maven artifacts your project depends on. Each dependency is specified as `groupId:artifactId: version`.

```yaml
dependencies:
com.github.lalyos:jfiglet: 0.0.9
info.picocli:picocli: 4.7.7
org.yaml:snakeyaml: '2.5'
```

**Note:** Version numbers should be quoted if they could be interpreted as numbers (e.g., `'2.5'` instead of `2.5`).

You can also use the list format:

```yaml
dependencies:
- com.github.lalyos:jfiglet:0.0.9
- info.picocli:picocli:4.7.7
```

#### repositories (Optional)

Custom Maven repositories to search for artifacts. Useful for private repositories or alternative artifact sources.

```yaml
repositories:
myrepo: https://my.repo.com/maven2
private: https://private.repo.com/releases
```

For repositories requiring authentication, set environment variables:
- `JPM_REPO_<name>_USER` - Username for the repository
- `JPM_REPO_<name>_PASSWORD` - Password for the repository

Example: For a repository named `private`, use `JPM_REPO_PRIVATE_USER` and `JPM_REPO_PRIVATE_PASSWORD`.

#### actions (Optional)

Custom commands that can be executed with `jpm do <action-name>`. Actions support variable substitution for cross-platform compatibility.

```yaml
actions:
build: "javac -cp {{deps}} -d {./target/classes} src{/}*.java"
run: "java -cp {{deps}}{:}{./target/classes} Main"
test: "java -cp {{deps}} org.junit.runner.JUnitCore TestSuite"
clean: "rm -rf {./target}"
```

See the [Actions](#actions) section above for details on variable substitution and using the `jpm do`, `jpm build`, `jpm run`, `jpm test`, and `jpm clean` commands.

### Minimal Example

A minimal `app.yml` file only needs dependencies:

```yaml
dependencies:
com.github.lalyos:jfiglet: 0.0.9
```

### Complete Example

Here's a complete example showing all available fields:

```yaml
name: HelloWorld
description: A simple Java application that prints ASCII art
documentation: https://github.com/user/hello-world
java: 11+
authors:
- Alice Developer <alice@example.com>
contributors:
- Bob Contributor <bob@example.com>

dependencies:
com.github.lalyos:jfiglet: 0.0.9
info.picocli:picocli: 4.7.7

repositories:
jitpack: https://jitpack.io

actions:
build: "javac -cp {{deps}} *.java"
run: "java -cp {{deps}} HelloWorld"
clean: "rm -f *.class"
```

## Development

To build the project simply run:
Expand Down