diff --git a/README.md b/README.md index 613e5cc..49b55fe 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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 @@ -194,6 +205,30 @@ Commands: exec Execute a shell command. ``` +### Common options + +These options are supported by all commands: + +``` + -c, --cache= + 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 to copy artifacts to + -L, --no-links Always copy artifacts, don't try to create symlinks + -r, --repo= + 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__USER and JPM_REPO__PASSWORD + environment variables. + -q, --quiet Don't output non-essential information + -v, --verbose Enable verbose output for debugging +``` + ### Commands #### search (alias: s) @@ -216,23 +251,6 @@ Options: -m, --max= Maximum number of results to return -a, --appinfo= App info file to use (default './app.yml') - -c, --cache= - 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 to copy artifacts to - -L, --no-links Always copy artifacts, don't try to create symlinks - -r, --repo= - 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__USER and JPM_REPO__PASSWORD - environment variables. - -q, --quiet Don't output non-essential information - -v, --verbose Enable verbose output for debugging Example: jpm search httpclient @@ -254,23 +272,6 @@ Parameters: Options: -a, --appinfo= App info file to use (default './app.yml') - -c, --cache= - 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 to copy artifacts to - -L, --no-links Always copy artifacts, don't try to create symlinks - -r, --repo= - 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__USER and JPM_REPO__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 @@ -295,23 +296,6 @@ Options: the mentioned artifacts and their dependencies, possibly removing other files present in the directory - -c, --cache= - 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 to copy artifacts to - -L, --no-links Always copy artifacts, don't try to create symlinks - -r, --repo= - 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__USER and JPM_REPO__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 @@ -333,22 +317,6 @@ Parameters: Options: -a, --appinfo= App info file to use (default './app.yml') - -c, --cache= - 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 to copy artifacts to - -L, --no-links Always copy artifacts, don't try to create symlinks - -r, --repo= - 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__USER and JPM_REPO__PASSWORD - environment variables. - -v, --verbose Enable verbose output for debugging Example: jpm path org.apache.httpcomponents:httpclient:4.5.14 @@ -373,23 +341,6 @@ Options: -l, --list List all available actions -a, --appinfo= App info file to use (default './app.yml') - -c, --cache= - 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 to copy artifacts to - -L, --no-links Always copy artifacts, don't try to create symlinks - -r, --repo= - 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__USER and JPM_REPO__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 @@ -414,14 +365,6 @@ Parameters: Options: -a, --appinfo= App info file to use (default './app.yml') - -c, --cache= - Directory where downloaded artifacts will be cached - -d, --directory= - Directory to copy artifacts to - -L, --no-links Always copy artifacts, don't try to create symlinks - -r, --repo= - URL to additional repository - -v, --verbose Enable verbose output for debugging Example: jpm build @@ -443,15 +386,6 @@ Parameters: Options: -a, --appinfo= App info file to use (default './app.yml') - -c, --cache= - Directory where downloaded artifacts will be cached - -d, --directory= - Directory to copy artifacts to - -L, --no-links Always copy artifacts, don't try to create symlinks - -r, --repo= - 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 @@ -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 + - Jane Smith +contributors: + - Bob Johnson + +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__USER` - Username for the repository +- `JPM_REPO__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 `. 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 +contributors: + - Bob Contributor + +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: