{"id":13434968,"url":"https://github.com/davidgiven/clue","last_synced_at":"2026-01-17T04:35:43.257Z","repository":{"id":35581215,"uuid":"39853737","full_name":"davidgiven/clue","owner":"davidgiven","description":"An experimental C to Javascript/Lua/Perl5/Lisp/Java compiler","archived":false,"fork":false,"pushed_at":"2015-07-28T19:32:31.000Z","size":560,"stargazers_count":145,"open_issues_count":4,"forks_count":18,"subscribers_count":11,"default_branch":"clue","last_synced_at":"2024-10-27T17:24:50.951Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidgiven.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-28T19:29:58.000Z","updated_at":"2024-09-11T04:33:32.000Z","dependencies_parsed_at":"2022-07-27T22:46:54.423Z","dependency_job_id":null,"html_url":"https://github.com/davidgiven/clue","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgiven%2Fclue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgiven%2Fclue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgiven%2Fclue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidgiven%2Fclue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidgiven","download_url":"https://codeload.github.com/davidgiven/clue/tar.gz/refs/heads/clue","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244143858,"owners_count":20405288,"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-07-31T03:00:28.964Z","updated_at":"2026-01-17T04:35:43.238Z","avatar_url":"https://github.com/davidgiven.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"                                  CLUE v0.6\n                                  =========\n\n                          (C) 2008-2013 David Given\n                                 2013-03-14\n\n\nINTRODUCTION\n============\n\nClue is an experimental C compiler for Lua, Javascript, Perl, Common Lisp,\nJava, and C. It compiles, eventually, ANSI C programs into a form which may\nbe run on a standard runtime for any of these languages.\n\nClue is EXPERIMENTAL and UNFINISHED. It is not suitable for any kind of\nproduction use. There are a number of C language features that are not\nimplemented yet, and it produces rather bad code. However, it will compile\na large number of non-trivial programs.\n\n\n\nINSTALLATION\n============\n\nInstallation is unfortunately rather involved and will only work on Unix-like\nsystems. I develop on Linux. You *may* be able to make it all work on Cygwin\nbut you're on your own. Sorry.\n\nTO RUN PROGRAMS BUILT WITH THE LUA51 BACK END:\n   ...you will need a Lua 5.1.3 interpreter (such as the stock Lua or Mike\n   Pall's LuaJIT) with the LuaSocket and BitLib modules installed.\n\nTO RUN PROGRAMS BUILT WITH THE LUA52 BACK END:\n   ...you will need a Lua 5.2 interpreter (such as the stock Lua or Mike\n   Pall's LuaJIT) with the LuaSocket module installed.\n\nTO RUN PROGRAMS BUILT WITH THE JAVASCRIPT BACK END:\n   ...you will need Node.\n\nTO RUN PROGRAMS BUILT WITH THE PERL5 BACK END:\n   ...you will need a Perl 5 interpreter with the Time::Hires module (which\n   is normally installed automatically).\n\nTO RUN PROGRAMS BUILT WITH THE COMMON LISP BACK END:\n   ...you will need a copy of the SBCL Common Lisp environment. It may or\n   may not work with other Common Lisp systems.\n   ...thanks to Peter Maydell (http://sourceforge.net/users/pm215) for\n   contributing this.\n   \nTO RUN PROGRAMS BUILT WITH THE C BACK END:\n   ...you will need a C toolchain --- but then if you can build Clue, you\n   will already have one.\n\nTO RUN PROGRAMS BUILT WITH THE JAVA BACK END:\n   ...you will need a JDK. Clue generates class files by producing Java source\n   code and compiling it, so you'll need a javac as well as a java interpreter.\n   I develop with the official Sun Java 6 distribution.\n         \nTO BUILD THE COMPILER:\n   \n1. Fetch sparse 0.4.1 from here:\n\n     http://www.kernel.org/pub/software/devel/sparse/\n\n   Apply the supplied sparse.patch file, compile it, and install it.    \n\n2. Edit the supplied pmfile and change the section at the top to point\n   at where you installed sparse's headers and libraries.\n   \n3. Do:\n\n     ./pm\n\n   Clue will then build the compiler and the modified Lua interpreter that's\n   used as an assembler.\n   \nClue is currently not designed to be installed anywhere; it should be run from\nthe place where you built it. I did warn you it was experimental...\n\n\n\nUSAGE\n=====\n\nYou may compile a C program as follows:\n\n\tbin/clue -m\u003cbackend\u003e test/helloworld.c \u003e output.\u003cextension\u003e\n\t\n\u003cbackend\u003e may be lua51, lua52, js, perl5, java or c.\n   \nThis will read in the source file, compile it and write out the result.\n\nOnce you have a runnable result, you may run it with the cluerun tool. This\nsets up the run-time environment needed to run Clue code.\n\n    ./cluerun -f output.lua\nor  ./cluerun -f output.js\nor  ./cluerun -f output.pl\nor  ./cluerun -f output.lisp\nor  ./cluerun -f output.j\nor  ./cluerun -f output.c\n\nBy default, cluerun will try to use LuaJIT for .lua files, SpiderMonkey\nfor .js files and Perl 5 for .pl files. You can change this with the -e\noption, which may have one of the following values:\n\n    lua51        standard Lua interpreter (version 5.1)\n    lua52        standard Lua interpreter (version 5.2)\n    luajit2-jon  Mike Pall's LuaJIT in JIT mode\n    js           Node V8 Javascript interpreter\n    perl5        Perl 5 interpreter\n    lisp         SBCL Common Lisp interpreter\n    j            standard Java compiler and interpreter\n    c            C compiler via gcc\n\nYou can pass arguments to the Clue program by suffixing cluerun with a --.\n\n    ./cluerun -e js -f output.js -- arg1 arg2 arg3\n\nYou may use multiple files --- all of the same type, of course --- and they\nwill get linked together and main() run.\n\n    ./cluerun -e js -f file1.js -f file2.js -f file3.js -- arg1 arg2 arg3   \n\nThis works to a certain extent (it's used by the benchmarks), but is still a\nbit problematic. (sparse has some bugs that cause prototyping symbols to\nsometimes not work correctly.)\n\n\n\nBENCHMARKING\n============\n\nClue is complete enough to run a number of benchmarks. These are located\nin the test directory.\n\nMost of the benchmarks are taken from the Computer Language Benchmark\nGame (neé the Great Computer Language Shootout), located here:\n\n    http://shootout.alioth.debian.org/\n    \nThe CLBG benchmarks can be run en mass using the supplied run-benchmarks\nscript. It will run each benchmark using gcc, clue via a Lua interpreter,\nand clue via LuaJIT (if you have it). (Note that the script does *not*\nuse the same number of iterations as the CLBG uses, as I'm not getting\nany younger.) However, the CLBG benchmarks are very inaccurate and they\nshould be considered unit tests only.\n\nAlso supplied is a version of the very elderly Whetstone benchmark. This\ncan be run as a normal program.\n\nSee README.benchmarks for the results I get on my machine.\n\n\n\nWRITING PROGRAMS WITH CLUE\n==========================\n\nClue supports standard ANSI C (C89, some C99, some bugs). Unfortunately,\nmost programmers don't! There are a number of places where Clue behaves\nvery differently to normal C compilers, \n\n- you may not cast any kind of pointer to a number, or vice\n  versa (except for the special case of constant 0, which may be\n  cast to any kind of pointer).\n  \n- you may not cast function pointers to object pointers or vice\n  versa.\n \n- accessing memory via the wrong kind of pointer is not supported. This\n  means you can't do this:\n  \n  {\n    void* p = \u0026fnord;\n    return *(int*)p;\n  }\n  \n  You *can* use unions to store two objects of different types at the same\n  memory location --- but accessing the wrong one will probably produce a\n  runtime error.\n  \n- sizeof(char) == sizeof(int) == sizeof(long) == sizeof(void(*)()) == 1.\n  sizeof(void*) == 2.\n\n- trying to operate on uninitialised memory will most likely produce a\n  runtime error (as it will probably be initialised to something that you\n  can't do things like arithmetic operations on). \n\n- the libc is *very* terse. I implemented only those functions necessary\n  to make the benchmarks work.\n\nViolating any of these will sometimes produce a compile-time error but\nmostly you'll get a really, really strange run-time error.\n\n\n\nBUGS\n====\n\nHahahaha! Hahahahahaha! Haha!\n\nOkay, there are some bugs. Did I mention this was experimental?\n\nThe ones I've actually noticed include, but are not limited to:\n\nCompiler bugs:\n\n- inline doesn't work.\n\n- Multiple declarations of items doesn't work. (This is a sparse bug.)\n\n- sparse can't always distinguish between different scalar types of the same\n  size, which means that backends can't distinguish between reals and integers;\n  this usually manifests itself in parameters being passed to functions in the\n  wrong register. This means that backends must use the same type to represent\n  both reals and integers, which prevents certain optimisations in c and java.\n  (This is a sparse bug.)\n  \n- Various compiler features aren't implemented yet, like switch or varargs.\n\nLibc bugs:\n\n- stdio can only read or write text on Lua; this causes clbg-mandelbrot to\n  produce invalid data when run using clue.\n  \n- printf is very basic and doesn't properly implement the printf spec\n  (different on each platform).\n  \n- the Common Lisp libc is only partially implemented, which means that the\n  benchmarks aren't run for it. \n\nThere are others. Oh, yes, there are others.\n  \n\n\nTODO\n====\n\nThere are a number of ways to take Clue further.\n\n- Add more targets. I'd like the Java target to emit bytecode; that way we\n  get a real goto implementation, which should boost performance. There's\n  also an experimental Common Lisp target that was contributed that needs a\n  libc to be useful. \n   \n- Finish the language coverage. There are a number of C language features\n  that I haven't gotten around to doing (like switch).  \n\n\nLICENSING\n=========\n\nDifferent parts of the supplied source are covered by different licenses.\n\ntest/clbg-*.c are very slightly tweaked (mostly changing %ld to %d in\nformat strings) versions of the Computer Language Benchmark Game\nbenchmarks. See http://shootout.alioth.debian.org. These are covered by the\nRevised BSD license. See\nhttp://shootout.alioth.debian.org/gp4/miscfile.php?file=license\u0026title=revised%20BSD%20license\nfor the text.\n\ntest/whetstone.c is a hacked copy of one of the million or so Whetstone\nvariations dating from the 1980s. It is, I believe, public domain. If anyone\nhas more information, please get in touch.\n\nsrc/clue/cg-lisp.c and src/lisp was contributed by Peter Maydell. It is\ncovered by the Revised BSD license (text below).\n\nPractically everything else was written by me, David Given, and is covered by\nthe Revised BSD license. The text follows:\n\nCopyright (c) 2008, David Given\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions\nare met:\n\n    * Redistributions of source code must retain the above copyright\n      notice, this list of conditions and the following disclaimer.\n    * Redistributions in binary form must reproduce the above copyright\n      notice, this list of conditions and the following disclaimer in\n      the documentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE \nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\nARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE \nLIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR \nCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF \nSUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS \nINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN \nCONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) \nARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.\n\n# $Id$\n# $HeadURL$\n# $LastChangedDate: 2008-07-19 23:13:17 +0100 (Sat, 19 Jul 2008) $\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidgiven%2Fclue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidgiven%2Fclue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidgiven%2Fclue/lists"}