||3 days ago|
|3rdPartySrc||6 months ago|
|VisualStudio/Cakelisp||10 months ago|
|doc||5 days ago|
|images||2 years ago|
|runtime||2 weeks ago|
|src||3 days ago|
|test||3 days ago|
|tools||2 weeks ago|
|.clang-format||2 years ago|
|.gitattributes||2 years ago|
|.gitignore||3 days ago|
|Bootstrap.cake||9 months ago|
|Bootstrap_MSVC.cake||8 months ago|
|Bootstrap_Mac.cake||8 months ago|
|Build.bat||5 days ago|
|Build.sh||5 days ago|
|BuildAndRunTests.sh||5 days ago|
|BuildAndRunTests_Mac.sh||12 months ago|
|BuildHotReloadLib.sh||2 years ago|
|Build_Mac.sh||5 days ago|
|Build_RunTests.bat||5 days ago|
|COPYING||1 year ago|
|CrossCompile_Windows.cake||9 months ago|
|LICENSE||2 years ago|
|LICENSE_EXCEPTION||2 years ago|
|ReadMe.org||5 days ago|
- Building Cakelisp itself
- Building a project using Cakelisp
- Learning Cakelisp
- Tooling support
- Similar applications/languages
This is a programming language where I can have my cake and eat it too.
Cakelisp is a compiled language ideal for high performance, iteratively-developed applications. There is an emphasis on compile-time code generation, modification, and execution. These features are used to acquire and build 3rd party dependencies, automatically instrument the code, generate introspection metadata, and do various other things that are normally impossible with most compiled languages.
It is implemented as a transpiler which generates C or C++ from an S-expression syntax.
Note that while Cakelisp has "Lisp" in the name, Cakelisp takes some inspiration from Lisp, but is not compatible and does not aspire to become "a Lisp". I was inspired by Naughty Dog's use of GOAL, GOOL, and Racket/Scheme (on their modern titles). I've also taken several ideas from Jonathan Blow's talks on Jai.
The metaprogramming capabilities of Lisp: True full-power macro support. Macros can use compile-time code execution to conditionally change what is output based on the context of the invocation
The performance of C: No heavyweight runtime, boxing/unboxing overhead, etc.
"Real" types: Types are identical to C types, e.g.
intis 32 bits with no sign bit or anything like other Lisp implementations do
No garbage collection: I primarily work on games, which make garbage collection pauses unacceptable. I also think garbage collectors add more complexity than manual management
Hot reloading: It should be possible to make modifications to functions and structures at runtime to quickly iterate
Truly seamless C and C++ interoperability: No bindings, no wrappers: C/C++ types and functions are as easy to declare and call as they are in C/C++. In order to support this, I've decided to ignore type deduction when possible and instead rely on the C compiler/linker to relay typing errors. Cakelisp will blindly generate what look like C/C++ function calls without knowing if that function actually exists, because the C/C++ compiler will tell us what the answer is
Compile-time code modification: After all macros are expanded, the programmer can specify compile-time functions which can do arbitrary modification of the expanded code. This makes it possible to validate functions, automatically insert profiling instrumentation (similar to this Jai demonstration), and other tasks which would be cumbersome or impossible to do with macros alone
Output human-readable C/C++ source and header files: This makes it possible to use Cakelisp in a subset of your project. It also means Cakelisp will work on any platform C/C++ works on. Generated code closely resembles the source Cakelisp code whenever possible
Build system: Simple projects will automatically be built and linked into an executable. Complex projects can use compile-time code execution to override stages of the build process. The code essentially knows how to build itself!
For more advantages, see doc/NeatUses.org.
Some of these features come naturally from using C as the backend. Eventually it would be cool to not have to generate C (e.g. generate LLVM bytecode instead), but that can a project for another time.
Cakelisp is copyright (C) 2021 Macoy Madson
GPL-3.0-or-later, with added Linking Over Controlled Interface exception.
runtime/ is licensed under MIT License.
Please see doc/Legal.org for a detailed explanation.
email@example.com if you would like to negotiate an exception for your use-case.
Building Cakelisp itself
doc/Tutorial_ProjectSetup.org provides a step-by-step tutorial on how to set up a Cakelisp project. More brief instructions follow.
cd cakelisp ./Build.sh
This script first builds cakelisp explicitly, then uses the
cakelisp_bootstrap_v2 executable to build Cakelisp using Cakelisp. Subsequent executions of
Build.sh will also build using Cakelisp, which means all the caching features will be in effect (making builds much faster).
You can then run
./bin/cakelisp. Have fun! A simple test:
./bin/cakelisp --execute test/Hello.cake
It shouldn't be hard to build Cakelisp using your favorite build system. Simply build all the
.cpp files in
UNIX defined), then link them into an executable which also links
-ldl. Leave out
Main.cpp and you can embed Cakelisp in a static or dynamic library!
Do the same as Linux, only call the
Build_Mac.sh script instead. (etc.)
Windows does not come with a compiler installed by default. In order to provide a solid "native" experience, Cakelisp supports MSVC. It should be possible to compile on Windows using MinGW as well (in which case, you should refer to the Linux instructions, or open an Issue requesting Windows-native MinGW bootstrap building).
Once you do have a compiler, I aspire to make Cakelisp the easiest way to make C/C++-based projects on Windows. You shouldn't need to touch Visual Studio project files ever again!
The following instructions will assume you are using MSVC.
Install Visual Studio. You can download the Community edition for free here.
Ensure that you pick the C++ track, and make sure the C++ Developer Tools box is checked (if you clicked C++, you shouldn't need to make any other changes).
Note that you need to upgrade depending on what kinds of projects you use, e.g. if you are in a team making proprietary software, you must pay for Professional or Enterprise
Download Cakelisp. If you have git or any git client installed, clone this repository using the URL provided on this page. If you don't have Git, download the
.zipfile from the repository home page
This should automatically find your Visual Studio and set the proper environment variables. If it doesn't, see the MSVC documentation on running from the command line. You may have to update the path to
Build.batto whatever Visual Studio version you installed. You should be able to find the script via searching for
C:\Program Files (x86)folder.
Check that the build succeeded. Cakelisp is first built manually, then bootstrap builds itself using
Bootstrap_MSVC.cake. You may need to modify
Bootstrap_MSVC.caketo change compiler settings. Subsequent executions of
Build.batwill use cached versions to only build changed files
If you have
bin/, you are ready to use Cakelisp! Due to the use of environment variables to select the compiler, you can only build programs if you've set the variables. To do so, refer to
Build.bat, or create a
.bat file based on this template:
echo off rem Set environment variables for compiler/linker selection rem Include help message in case this file isn't present if exist "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat" ( call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat" ) else ( echo This script builds using MSVC. echo You must download and install MSVC before it will work. Download it here: echo https://visualstudio.microsoft.com/downloads/ echo Select workloads for C++ projects. Ensure you install the C++ developer tools. echo If you're still seeing this, you may need to edit Build.bat to your vcvars path echo Please see the following link: echo https://docs.microsoft.com/en-us/cpp/build/building-on-the-command-line?view=msvc-160 goto fail ) rem EDIT ME! If you keep this build script in the same directory as your project, update rem "bin\cakelisp.exe" to wherever you have a built version of Cakelisp rem Add --execute before the .cake files to run your project after building "bin\cakelisp.exe" YourProgram.cake rem Make the result clear @if %ERRORLEVEL% == 0 ( echo Success! goto success ) else ( echo Error while building goto fail ) :fail goto end :success goto end :end rem Give the user a chance to read the input (not required) pause
Building from Visual Studio
It is also possible to create a Visual Studio project to build Cakelisp. This is especially useful if you are debugging Cakelisp itself.
You can refer to an existing project in
cakelisp/VisualStudio. The steps to create a new project are as follows:
Open Visual Studio
File -> New -> New Project
Visual C++ -> Empty Project
Set the name, location, and solution as desired, then click OK
Project -> Add Existing Item
cakelisp/src, then select all the files (via
Ctrl-A, etc.) and click Add. This makes Cakelisp itself built by Visual Studio (i.e., not bootstrap built)
Build -> Configuration Manager
Active solution platform. Cakelisp works in
Win32, but you should probably be using
x64anyways, because it's the dominant architecture, and the hard-coded compile/link commands assume
Project -> <Project Name> Properties...
Working Directoryto wherever your project's working directory is, e.g. where your
Command Argumentsto the
.cakefiles you want to build. You can leave this empty to see the Cakelisp help page
Environmentto include the necessary environment variables. This is required so that Cakelisp knows how to find MSVC when launching it as a sub-process. The easiest way to find these is to open a Command Prompt, then run a
vcvarsscript. For example, I run the following:
"C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"
Your path may be different based on your Visual Studio version and installation. See documentation on how to find this file.
setin that same Command Prompt. Select all of the text output by that command and hit Enter to copy it. Finally, return to the
Environmentsetting in Visual Studio, click the down arrow on the field, then
<Edit...>. Paste into the top text field, then hit OK.
Configuration Properties -> C/C++ -> Preprocessor
Double click or
Preprocessor Definitionsfield and add the following to the beginning:
CAKELISP_EXPORTINGindicates Cakelisp should export its symbols to DLLs. The
CRTdefinition is going to be removed eventually; it makes MSVC more lenient with some errors Cakelisp has. The
WINDOWSdefinition ensures you build with Cakelisp's Windows-specific code enabled
F5or go to
Debug -> Start Debugging. Visual Studio will build Cakelisp, and if it succeeds, launch Cakelisp. If you have no
Command Argumentsset, you should see the Cakelisp help output in a command window.
This project is for building Cakelisp itself; you don't need to make any new projects for your projects written in Cakelisp (in
.cake files). Change the
Debugging -> Command Arguments setting to build different Cakelisp files, or change the
Working Directory to build a different Cakelisp project (e.g. one in a separate repository).
Currently, Cakelisp has no dependencies other than:
C++ STL and runtime: These are normally included in your toolset
Child-process creation: On *nix,
unistd.h. On Windows,
Dynamic loading: On *nix,
libdl. On Windows,
File modification times: On *nix,
C++ compiler toolchain: Cakelisp needs a C++ compiler and linker to support compile-time code execution, which is used for macros and generators
I'm going to try to keep it very lightweight. It should make it straightforward to port Cakelisp to other platforms.
Note that your project does not have to include or link any of these unless you use hot-reloading, which requires dynamic loading. This means projects using Cakelisp are just as portable as any C/C++ project - there's no runtime to port (except hot-reloading, which is optional).
Building a project using Cakelisp
Cakelisp will automatically figure out how to build simple projects into executables.
For more complex projects, many hooks and variables are provided for overriding the build process. Your code is defined in Cakelisp, and so are all build commands. This gives the code the ability to know how to build itself.
For example, you could have a
.cake module which includes a 3rd party graphics library. By importing that module, the module's compile-time hooks are added to the build process, which can do things like add the 3rd party graphics library's
lib files to the link stage.
The build hooks are all regular Cakelisp code, which means you could do something as advanced as cloning a repository from the internet, launching a subprocess to
make that project, then let Cakelisp finish the build by linking the output libraries.
One huge advantage to defining your build process in a "real" programming language (as opposed to a domain-specific language interpreted by a build system) is that you can attach a debugger and single step through the build process when things go wrong.
See doc/ToolsIntegration.org for e.g. editor integrations.
A build system may work with Cakelisp, because Cakelisp outputs C/C++ source/header files. Cakelisp must run before your regular build system runs, or in a stage where Cakelisp can create and add files to the build. This is because Cakelisp handles its own modules such that adding support to an existing build system would be challenging.
Ideally, you should be able to rely on Cakelisp's built-in build system. This allows Cakelisp files to know how to build themselves.
If you do want to use your build system instead of Cakelisp, pass
cakelisp so that Cakelisp generates the files but doesn't build them.
See doc/Debugging.org. Cakelisp doesn't really have an interpreter. Cakelisp always generates C/C++ code to do meaningful work. This means the Cakelisp transpiler, macros, generators, and final code output can be debugged using a regular C/C++ debugger like GDB, LLDB, or Visual Studio Debugger.
Mapping files will make it possible to step through code in the Cakelisp language (i.e. not in the generated language). This is similar to how debuggers allow you to step through code in C files, when under the hood it's actually stepping through machine code. It will require building support into your editor in order to properly jump to the right Cakelisp file and line (among other things).
See doc/VsOtherLanguages.org for projects similar to Cakelisp.