{"id":19838972,"url":"https://github.com/objectionary/jeo-maven-plugin","last_synced_at":"2025-05-01T18:31:48.437Z","repository":{"id":185068333,"uuid":"671896902","full_name":"objectionary/jeo-maven-plugin","owner":"objectionary","description":"This Maven plugin converts Java Bytecode binary files to EOLANG programs that use the \"opcode\" atom","archived":false,"fork":false,"pushed_at":"2024-11-05T13:58:23.000Z","size":13049,"stargazers_count":11,"open_issues_count":29,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-05T14:27:22.842Z","etag":null,"topics":["bytecode","bytecode-interpreter","code-generation","code-optimization","eolang","java","maven-plugin"],"latest_commit_sha":null,"homepage":"https://www.objectionary.com/jeo-maven-plugin/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/objectionary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-28T11:50:33.000Z","updated_at":"2024-11-05T13:18:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"fb620989-3430-41ef-ae83-fce62e5f63ea","html_url":"https://github.com/objectionary/jeo-maven-plugin","commit_stats":null,"previous_names":["objectionary/jeo-maven-plugin"],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectionary%2Fjeo-maven-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectionary%2Fjeo-maven-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectionary%2Fjeo-maven-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/objectionary%2Fjeo-maven-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/objectionary","download_url":"https://codeload.github.com/objectionary/jeo-maven-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224270874,"owners_count":17283872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bytecode","bytecode-interpreter","code-generation","code-optimization","eolang","java","maven-plugin"],"created_at":"2024-11-12T12:19:47.570Z","updated_at":"2025-05-01T18:31:48.427Z","avatar_url":"https://github.com/objectionary.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg alt=\"logo\" src=\"https://www.objectionary.com/cactus.svg\" height=\"100px\" /\u003e\n\n[![Maven Central](https://img.shields.io/maven-central/v/org.eolang/jeo-maven-plugin.svg)](https://maven-badges.herokuapp.com/maven-central/org.eolang/jeo-maven-plugin)\n[![Javadoc](https://www.javadoc.io/badge/org.eolang/jeo-maven-plugin.svg)](https://www.javadoc.io/doc/org.eolang/jeo-maven-plugin)\n[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE.txt)\n[![Hits-of-Code](https://hitsofcode.com/github/objectionary/jeo-maven-plugin?branch=master\u0026label=Hits-of-Code)](https://hitsofcode.com/github/objectionary/jeo-maven-plugin/view?branch=master\u0026label=Hits-of-Code)\n![Lines of code](https://sloc.xyz/github/objectionary/jeo-maven-plugin)\n[![codecov](https://codecov.io/gh/objectionary/jeo-maven-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/objectionary/jeo-maven-plugin)\n\n**jeo-maven-plugin** is a Maven plugin dedicated to disassembling Java bytecode.\nThe process involves translating the Java bytecode into\nthe [EO](https://github.com/objectionary/eo)\nprogramming language.\nThe plugin also provides the ability to assemble EO back into Java bytecode.\n\n# How to use\n\nYou need at least **Maven 3.1+** and **Java 11+** to run the plugin.\n(Actually, the plugin requires **Java 8+**, but since the main\ndependency [eo](https://github.com/objectionary/eo) requires **Java 11**,\nwe are obligated to use it as well.)\n\nThe plugin can convert compiled `.class` files into EO by using\nthe `disassemble` goal.\nThe `assemble` goal can convert EO back into bytecode.\nThe default phase for the plugin\nis [process-classes](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html#default-lifecycle).\n\nTo optimize java bytecode you need to use both goals in the following order:\n\n* `disassemble` create EO files in the `target/generated-sources`\n  directory.\n* Provide your optimizations are applied to the EO files\n  in the `target/generated-sources` directory.\n* `assemble` scans the `target/generated-sources` directory for EO\n  files and converts them back to Java bytecode.\n\nMore details about plugin usage you can find in our\n[Maven site](https://objectionary.github.io/jeo-maven-plugin).\n\n## Invoke the plugin from the command line\n\nYou can run the plugin directly from the command line using the following\ncommands:\n\n```bash\nmvn jeo:disassemble\n```\n\nor\n\n```bash\nmvn jeo:assemble\n```\n\n## Invoke the plugin from the Maven lifecycle\n\nYou can run the plugin from the Maven lifecycle by adding the following\nconfiguration to your `pom.xml` file:\n\n```xml\n\n\u003cbuild\u003e\n  \u003cplugins\u003e\n    \u003cplugin\u003e\n      \u003cgroupId\u003eorg.eolang\u003c/groupId\u003e\n      \u003cartifactId\u003ejeo-maven-plugin\u003c/artifactId\u003e\n      \u003cversion\u003e0.10.0\u003c/version\u003e\n      \u003cexecutions\u003e\n        \u003cexecution\u003e\n          \u003cid\u003ebytecode-to-eo\u003c/id\u003e\n          \u003cphase\u003eprocess-classes\u003c/phase\u003e\n          \u003cgoals\u003e\n            \u003cgoal\u003edisassemble\u003c/goal\u003e\n          \u003c/goals\u003e\n        \u003c/execution\u003e\n        \u003cexecution\u003e\n          \u003cid\u003eeo-to-bytecode\u003c/id\u003e\n          \u003cphase\u003eprocess-classes\u003c/phase\u003e\n          \u003cgoals\u003e\n            \u003cgoal\u003eassemble\u003c/goal\u003e\n          \u003c/goals\u003e\n        \u003c/execution\u003e\n      \u003c/executions\u003e\n    \u003c/plugin\u003e\n  \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n### Include debug information\n\nIn order to include debug information in the generated EO files, you can set\n`debug` option.\n\n```xml\n\n\u003cconfiguration\u003e\n  \u003cmode\u003edebug\u003c/mode\u003e\n\u003c/configuration\u003e\n```\n\nThis option will add line numbers and local variable names to the EO files\ntogether with their corresponding labels.\n\n### Disable bytecode verification\n\nEach time the plugin converts EO back to bytecode, it verifies it. If the\nverification fails, the build also fails. You can disable this verification by\nsetting the `skipVerification` parameter to `true`:\n\n```xml\n\n\u003cconfiguration\u003e\n  \u003cskipVerification\u003etrue\u003c/skipVerification\u003e\n\u003c/configuration\u003e\n```\n\nAt times, it might be beneficial to generate intentionally flawed bytecode.\n\n### Enable XMIR Verification\n\nAfter generation XMIR or before `assemble` goal,\nyou might need to check its correctness.\nWe do it by using [objectionary/lints](https://github.com/objectionary/lints)\nrepository.\nBy default, the plugin does not run lints.\nTo enable them, you need to set `xmirVerification` to `true`:\n\n```xml\n\n\u003cconfiguration\u003e\n  \u003cxmirVerification\u003etrue\u003c/xmirVerification\u003e\n\u003c/configuration\u003e\n```\n\n## Disassembling Example\n\nThe plugin can transform Java bytecode into EO and back. Usually, the plugin\ntransforms each bytecode class file into a separate EO file, maintaining a\none-to-one relationship. If the Java class has name `Application.class`, the EO\nfile will have `Application.xmir` file.\n\nFor example, consider the following Java class:\n\n```java\npackage org.eolang.jeo;\n\npublic class Application {\n    public static void main(String[] args) {\n        System.out.println(\"Hello, World!\");\n    }\n}\n```\n\nwith the following bytecode representation:\n\n```bytecode\n{\n  public org.eolang.jeo.Application();\n    descriptor: ()V\n    flags: (0x0001) ACC_PUBLIC\n    Code:\n      stack=1, locals=1, args_size=1\n         0: aload_0\n         1: invokespecial #1                  // Method java/lang/Object.\"\u003cinit\u003e\":()V\n         4: return\n      LineNumberTable:\n        line 3: 0\n      LocalVariableTable:\n        Start  Length  Slot  Name   Signature\n            0       5     0  this   Lorg/eolang/jeo/Application;\n\n  public static void main(java.lang.String[]);\n    descriptor: ([Ljava/lang/String;)V\n    flags: (0x0009) ACC_PUBLIC, ACC_STATIC\n    Code:\n      stack=2, locals=1, args_size=1\n         0: getstatic     #7                  // Field java/lang/System.out:Ljava/io/PrintStream;\n         3: ldc           #13                 // String Hello, World!\n         5: invokevirtual #15                 // Method java/io/PrintStream.println:(Ljava/lang/String;)V\n         8: return\n      LineNumberTable:\n        line 5: 0\n        line 6: 8\n      LocalVariableTable:\n        Start  Length  Slot  Name   Signature\n            0       9     0  args   [Ljava/lang/String;\n}\n```\n\nAfter running the `jeo:disassemble` goal, the plugin will generate the\nfollowing EO:\n\n```eo\n+package j$org.j$eolang.j$jeo\n\njeo.class \u003e j$Application\n  jeo.int \u003e version\n    00-00-00-00-00-00-00-34\n  jeo.int \u003e access\n    00-00-00-00-00-00-00-21\n  \"java/lang/Object\" \u003e supername\n  jeo.seq.of0 \u003e interfaces-696199744\n  jeo.method \u003e j$object@init@-%28%29V\n    jeo.int\n      00-00-00-00-00-00-00-01\n    \"()V\"\n    \"\"\n    jeo.seq.of0 \u003e aca3ae21-f727-41cc-b8df-791e7031904e-1635871459\n    jeo.maxs\n      jeo.int\n        00-00-00-00-00-00-00-01\n      jeo.int\n        00-00-00-00-00-00-00-01\n    jeo.params\n    jeo.seq.of0 \u003e annotations-1586121642\n    jeo.seq.of3 \u003e body-1998918745\n      jeo.opcode.aload\n        jeo.int\n          00-00-00-00-00-00-00-19\n        jeo.int\n          00-00-00-00-00-00-00-00\n      jeo.opcode.invokespecial\n        jeo.int\n          00-00-00-00-00-00-00-B7\n        \"java/lang/Object\"\n        \"\u003cinit\u003e\"\n        \"()V\"\n        jeo.bool\n          00-\n      jeo.opcode.return\n        jeo.int\n          00-00-00-00-00-00-00-B1\n    jeo.seq.of0 \u003e trycatchblocks-object@init@-1849817803\n    jeo.seq.of0 \u003e local-variable-table-1794934203\n  jeo.method \u003e j$main-%28%5BLjava%2Flang%2FString%3B%29V\n    jeo.int\n      00-00-00-00-00-00-00-09\n    \"([Ljava/lang/String;)V\"\n    \"\"\n    jeo.seq.of0 \u003e f6c6c536-0b96-4357-bbba-d2966968b266-658978372\n    jeo.maxs\n      jeo.int\n        00-00-00-00-00-00-00-02\n      jeo.int\n        00-00-00-00-00-00-00-01\n    jeo.params\n      jeo.param \u003e param-%5BLjava%2Flang%2FString%3B-arg0-0-0-1064778491\n        jeo.seq.of0 \u003e param-annotations-0-666850426\n    jeo.seq.of0 \u003e annotations-639467587\n    jeo.seq.of4 \u003e body-1023152593\n      jeo.opcode.getstatic\n        jeo.int\n          00-00-00-00-00-00-00-B2\n        \"java/lang/System\"\n        \"out\"\n        \"Ljava/io/PrintStream;\"\n      jeo.opcode.ldc\n        jeo.int\n          00-00-00-00-00-00-00-12\n        \"Hello, World!\"\n      jeo.opcode.invokevirtual\n        jeo.int\n          00-00-00-00-00-00-00-B6\n        \"java/io/PrintStream\"\n        \"println\"\n        \"(Ljava/lang/String;)V\"\n        jeo.bool\n          00-\n      jeo.opcode.return\n        jeo.int\n          00-00-00-00-00-00-00-B1\n    jeo.seq.of0 \u003e trycatchblocks-main-727934521\n    jeo.seq.of0 \u003e local-variable-table-2134319645\n  jeo.seq.of0 \u003e annotations-785801830\n  jeo.seq.of0 \u003e attributes-744976367\n```\n\nAs you can see, there are many EO objects that represent the Java bytecode\nprimitives, like `jeo.opcode`, `jeo.int`, `jeo.method`, etc.\n\n## Full List of Jeo Objects\n\nDuring decompilation, the `jeo-maven-plugin` creates a set of objects\nrepresenting bytecode primitives.\nThese objects provide a way to handle various aspects of Java bytecode.\nBelow is the full list of these objects, grouped by category:\n\n---\n\n### Bytecode Instructions\n\n- **`jeo.opcode.*`**\n  Represents a single bytecode instruction like `aload_0`, `iconst_0`, etc.\n\n### Classes, Methods, and Fields\n\n- **`jeo.class`**\n  Represents a Java class.\n- **`jeo.method`**\n  Represents a Java method.\n- **`jeo.field`**\n  Represents a Java field.\n- **`jeo.params`**\n  Represents method parameters.\n- **`jeo.param`**\n  Represents a single method parameter.\n- **`jeo.maxs`**\n  Represents the maximum stack and local variable sizes.\n\n### Primitive Values\n\n- **`jeo.int`** - Represents an integer value.\n- **`jeo.bool`** - Represents a boolean value.\n- **`jeo.string`** - Represents a string value.\n- **`jeo.float`** - Represents a float value.\n- **`jeo.double`** - Represents a double value.\n- **`jeo.long`** - Represents a long value.\n- **`jeo.char`** - Represents a char value.\n- **`jeo.short`** - Represents a short value.\n- **`jeo.byte`** - Represents a byte value.\n- **`jeo.bytes`** - Represents a byte array.\n\n### Collections and Complex Types\n\n- **`jeo.nullable`**\n  Represents an object that can be `null`.\n- **`jeo.array`**\n  Represents an array of objects.\n- **`jeo.type`**\n  Represents a Java type.\n- **`jeo.seq.*`**\n  Represents a sequence of objects with a specific size,\n  like `jeo.seq.of0`, `jeo.seq.of1`, etc.\n\n### Annotations and Metadata\n\n- **`jeo.annotation`**\n  Represents a Java annotation.\n- **`jeo.annotation-property`**\n  Represents a single annotation element.\n- **`jeo.annotation-default-value`**\n  Represents a default value of a Java interface method or annotation property.\n- **`jeo.inner-class`**\n  Represents a Java inner class annotation property.\n\n### Local Variables and Control Flow\n\n- **`jeo.local-variable`**\n  Represents a local variable entry.\n- **`jeo.try-catch`**\n  Represents a try-catch block.\n\n### Labels, Handles, Frames\n\n- **`jeo.label`**\n  Represents a Java label.\n- **`jeo.handle`**\n  Represents a Java method handle.\n- **`jeo.frame`**\n  Represents a stack frame.\n\n## How to Build the Plugin\n\nTo build the plugin from the source code, you need to clone the repository and\nrun the following command:\n\n```bash\nmvn clean install -Pqulice,long\n```\n\nPay attention to the `qulice` profile, which activates the static analysis\ntools. The `long` profile is optional and runs the full test suite, including\nlong-running integration tests.\n\n\n## How to Run Benchmarks\n\nTo run the benchmarks, you need to execute the following command:\n\n```bash\nmvn clean verify -Pbenchmark\n```\n\nBefore running the benchmarks, make sure you have the `.env` file in the root\ndirectory of the project. The file should contain the following environment\nvariables:\n\n```bash\nPROFILER=/path/to/async-profiler/profiler.sh\n```\n\n## How to Contribute\n\nFork repository, make changes, then send us\na [pull request](https://www.yegor256.com/2014/04/15/github-guidelines.html).\nWe will review your changes and apply them to the `master` branch shortly,\nprovided they don't violate our quality standards. To avoid frustration,\nbefore sending us your pull request please run full Maven build:\n\n```bash\n$ mvn clean install -Pqulice\n```\n\nYou will need [Maven 3.3+](https://maven.apache.org) and Java 11+ installed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobjectionary%2Fjeo-maven-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fobjectionary%2Fjeo-maven-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fobjectionary%2Fjeo-maven-plugin/lists"}