{"id":13621250,"url":"https://github.com/davidar/lljvm","last_synced_at":"2025-04-06T04:09:39.456Z","repository":{"id":66883527,"uuid":"383490","full_name":"davidar/lljvm","owner":"davidar","description":"Low Level Java Virtual Machine","archived":false,"fork":false,"pushed_at":"2018-08-15T09:15:26.000Z","size":251,"stargazers_count":481,"open_issues_count":9,"forks_count":63,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-03-30T03:05:17.111Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://davidar.io","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/davidar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2009-11-24T05:03:08.000Z","updated_at":"2025-03-22T23:05:08.000Z","dependencies_parsed_at":"2023-06-25T23:57:28.418Z","dependency_job_id":null,"html_url":"https://github.com/davidar/lljvm","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Flljvm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Flljvm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Flljvm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidar%2Flljvm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidar","download_url":"https://codeload.github.com/davidar/lljvm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247430869,"owners_count":20937874,"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":[],"created_at":"2024-08-01T21:01:03.980Z","updated_at":"2025-04-06T04:09:39.286Z","avatar_url":"https://github.com/davidar.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# LLJVM\n\n**LLJVM** provides a set of tools and libraries for running comparatively low level\nlanguages (such as C) on the JVM.\n\nThe C to JVM bytecode compilation provided by LLJVM involves several steps. Source code is first compiled to [LLVM][llvm] intermediate representation (IR) by a frontend such as `llvm-gcc` or [clang][clang]. LLVM IR is then translated to [Jasmin][jasmin] assembly code, linked against other Java classes, and then assembled to JVM bytecode.\n\nThe use of LLVM IR as the intermediate representation allows more information about the source program to be preserved, compared to other methods which use MIPS binary as the intermediate representation (such as [NestedVM][nestedvm] and [Cibyl][cibyl]). For example, functions are mapped to individual JVM methods, and all function calls are made with native JVM invocation instructions. This allows compiled code to be linked against arbitrary Java classes, and Java programs to natively call individual functions in the compiled code. It also allows programs to be split across multiple classes (comparable to dynamic linking), rather than statically linking everything into a single class.\n\nAlso note that while C is currently the only supported input language, any language with a compiler targeting LLVM IR could potentially be supported.\n\nThis project is currently unmaintained. You may be interested in:\n\n- [one of the forks](https://github.com/davidar/lljvm/network)\n- [LLJVM Translator](https://github.com/maropu/lljvm-translator)\n\n\n## QUICKSTART\n\nFor a **quick demonstration** of some pre-compiled classes, download the [runtime library][lljvm-jar] and the [demo package][lljvm-demo-jar] to a directory on your machine, and run `java -jar lljvm-demo-0.2.jar`.\n\nTo **quickly start** translating your own programs you might want to use [Docker][docker]. Getting LLJVM to run on modern machines (and keeping it running) can be quite tricky as it depends heavily on an old version of LLVM. As an alternative, Martin Haye has set up a virtual machine image [here][mhaye-lljvm] that is pre-configured for and includes LLJVM. Install Docker (you may need Boot2Docker) and start it this way: `docker run -i -v /your/project/dir:/project -t mhaye/lljvm /bin/bash`\n\nTo compile LLJVM from source, follow the instructions below. If you have problems compiling from source and are running Linux on an i386-compatible platform, download the [binary release][lljvm-bin], extract it, and download the [runtime library][lljvm-jar] into the resulting directory.\n\n- [HN comments][hn-lljvm]\n- 2009-2015 [David A Roberts](https://davidar.io)\n\n\n## INSTALLATION\n[LLVM 2.7][llvm] must be installed to compile and run LLJVM. [Jasmin][jasmin] is needed for\nassembling JVM bytecode.\n\nTo compile LLJVM, simply call `make` in the project root directory, and call\n`make check` to run the testsuite.\n\nTo generate the the documentation for the java packages and the backend, call\n`make doc`, which will generate HTML documentation in `doc/java/` and\n`doc/backend/` respectively. PDF documentation for the backend can be obtained by\ncalling `make doc-pdf` (requires PDFLaTeX), which will generate\n`doc/backend.pdf`. A zip archive containing all of the documentation can be\ncreated by calling `make doc-zip`.\n\n\n## C COMPILER\nThe `lljvm-cc` frontend ties together several components to provide a C source\ncode to JVM class file compiler.\n\nIn order to use the frontend, either `llvm-gcc` or `clang` must be installed.\n`llvm-gcc` is recommended, and is used instead of `clang` if both are available.\nIt is also required that the classpath contain [jasmin.jar][jasmin-jar].\n\nTo compile a small number of source files to a class file, the following style\nof command can be used:\n\n    lljvm-cc foo.c bar.c -o foo\n\nThis will generate `foo.class`, as well as a shell script `foo`, which sets the\nclasspath appropriately and executes the classfile with the arguments passed to\nit. This allows the class to be called in the same way as any other executable.\nIf calling the class without the shell script, note that the entire list of\narguments must be passed to the class, including argument 0 (the name of the\ncommand).\n\nFor a larger number of source files, it is often more efficient to separately\ncompile each file to an object file as needed:\n\n    lljvm-cc -c foo.c\nthen link the object files together into a class file:\n\n    lljvm-cc -link foo.o bar.o baz.o -o foo\nNote that the -link flag must be used if object files are being supplied\ninstead of source files.\n\nTo link the object files together as a library instead of an executable,\n`-link-as-library` can be passed instead of `-link`. In this case the shell script\nwill not be generated.\n\nTo link against a library generated by `lljvm-cc`, the `-l\u003cname\u003e` flag can be used.\nThis will search for a library in the classpath called `lib\u003cname\u003e.class`.\nAdditional directories can be added to the classpath with the `-L\u003cpath\u003e` flag.\nSuch additions to the classpath will also be added to the shell script, so\nwhen linking an executable, the `-L` flag must be passed for each directory\ncontaining libraries needed by the executable (except the current directory and\ndirectories in the system classpath).\n\nAn exception to the above is the `-lm` flag. This will not search for `libm.class`,\nbut will rather link against `java.lang.Math` and `lljvm.runtime.Math`. Also, `-lc`\nshould not be used as `libc` is linked by default. If this is not desired, then\nthe `-nostdlib` flag can be used.\n\nBy default all classes generated are placed in the default package. To assign\nthe class to a specific package, the `-classname` flag can be used. For example,\nthe following command:\n\n    lljvm-cc ... -classname=com.example.foo -o bar/baz\nwill create a class named foo, in the package com.example, placing it in the\ndirectory `bar/com/example/`. The shell script will be output to `bar/baz`.\n\nIf the `-g3` flag is used, then Jasmin assembly with full debugging information\nwill be output to `\u003coutput\u003e.j`.\n\nIn addition to the above flags, any flag accepted by `gcc` or `ld` can also be\nused. However, sometimes these flags may not be passed to the correct\ncomponent (this is a bug with `lljvm-cc` and should be reported).\n\nThe frontend can also be used to compile `autoconf`-based projects relatively\neasily (although sometimes some changes to the project's build system may be\nrequired):\n\n    ./configure CC=lljvm-cc LD='lljvm-cc -link'\n    make CCLD='lljvm-cc -link'\n\n\n## DEMO\nTo demonstrate the capabilities of LLJVM, several common software packages can\nbe compiled with `lljvm-cc` by entering the `demo/` subdirectory and calling\n`make`. To verify that all of these compiled correctly, call `make check`.\n\nA JAR archive containing all of the demo programs can be created by calling\n`make demo` in the project root directory. For usage information, execute the\nJAR in the project root directory with no arguments:\n\n    java -jar lljvm-demo.jar\n\n\n## BACKEND\nThe LLJVM Backend transforms LLVM IR into Jasmin assembly code.\nIt can be invoked by:\n\n    lljvm-backend foo.bc \u003e foo.j\n\nThere are two flags that are accepted by the backend: `-classname` and `-g`.\nRun `lljvm-backend --help` for more information.\n\nThe output file should then be linked by the LLJVM Linker (see below), and\nassembled into a class file by [Jasmin][jasmin]:\n\n    java -jar jasmin.jar foo.j\n\n\n## RUNTIME\nThe LLVJM Runtime has three components, the Core Runtime (`lljvm.runtime`), the\nI/O Support Library (`lljvm.io`), and the C Standard Library (`lljvm.lib.c`). See\nthe JavaDoc documentation for further details on the former two. The latter is\n[Newlib][newlib] compiled to JVM bytecode by `lljvm-cc`.\n\n\n## TOOLS\nThere are two command-line tools available: the linker, and the info utility.\nThere are several ways to invoke these tools. The simplest way is to call them\ndirectly from the jar archive:\n\n    java -jar lljvm.jar \u003ccmd\u003e args...\n\nAlternatively, if `lljvm.jar` is already in the classpath, one of the following\ncan be used:\n\n    java lljvm.tools.Main \u003ccmd\u003e args...\n    java lljvm.tools.\u003ccmd\u003e.Main args...\n\n\n## LINKER\nThe LLJVM Linker qualifies references to external methods and fields in Jasmin\nassembly code. At the top of the code (before any `.method` directives), external\nreferences should be specified through the `.extern` pseudo-directive, such as:\n\n    .extern field foo I\n    .extern method bar(I)V\n\nThen the linker can be invoked by:\n\n    java -jar lljvm.jar ld LIBRARY... \u003c INPUT.j \u003e OUTPUT.j\n\nFor example, the following assembly code:\n\n    .extern method cos(D)D\n    .extern field NULL I\n    ...\n    invokestatic cos(D)D\n    getstatic NULL I\n    CLASSFORMETHOD cos(D)D\nlinked with the command:\n\n    java -jar lljvm.jar ld java.lang.Math lljvm.runtime.Memory\nwould produce:\n\n    ...\n    invokestatic java/lang/Math/cos(D)D\n    getstatic lljvm/runtime/Memory/NULL I\n    ldc \"java/lang/Math\"\n\n\n## INFO\nThe info utility lists the type signatures of the public static fields and\nmethods provided by a class. For example, to list those provided by `libc`:\n\n    java -jar lljvm.jar info lljvm.lib.c\n\nBy default, any identifiers beginning with an underscore are omitted. To\ndisable this behaviour, pass the `-v` flag:\n\n    java -jar lljvm.jar info -v lljvm.lib.c\n\n\n[llvm]: http://llvm.org/\n[jasmin]: https://github.com/davidar/jasmin\n[jasmin-jar]: https://github.com/davidar/jasmin/raw/master/jasmin.jar\n[newlib]: http://sourceware.org/newlib/\n[hn-lljvm]: http://news.ycombinator.com/item?id=961834\n[lljvm-jar]: https://github.com/davidar/lljvm/releases/download/0.2/lljvm-0.2.jar\n[docker]: https://www.docker.com/\n[mhaye-lljvm]: https://registry.hub.docker.com/u/mhaye/lljvm/\n[lljvm-demo-jar]: https://github.com/davidar/lljvm/releases/download/0.2/lljvm-demo-0.2.jar\n[lljvm-bin]: https://github.com/davidar/lljvm/releases/download/0.2/lljvm-bin-linux-i386-0.2.tar.gz\n[clang]: http://clang.llvm.org/\n[nestedvm]: http://nestedvm.ibex.org/\n[cibyl]: https://github.com/SimonKagstrom/cibyl\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidar%2Flljvm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidar%2Flljvm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidar%2Flljvm/lists"}