Initial version, pending windows

ckiwi/.clang-format → .clang-format

@@ -27,7 +27,7 @@ BreakBeforeTernaryOperators: true
 BreakConstructorInitializers: AfterColon
 BreakInheritanceList: AfterColon
 BreakStringLiterals: false
-ColumnLimit: 90
+ColumnLimit: 98
 CompactNamespaces: false
 ConstructorInitializerAllOnOneLineOrOnePerLine: true
 ConstructorInitializerIndentWidth: 4
@@ -65,7 +65,7 @@ PointerAlignment: Left
 ReferenceAlignment: Left              # New in v13. int &name  ==>  int& name
 ReflowComments: false
 SeparateDefinitionBlocks: Always      # New in v14.
-SortIncludes: true
+SortIncludes: false
 SortUsingDeclarations: true
 SpaceAfterCStyleCast: false
 SpaceAfterLogicalNot: false

.editorconfig

@@ -7,5 +7,4 @@ insert_final_newline = true
 [{*.lua,*.rockspec,.luacov}]
 indent_style = space
 indent_size = 3
-call_parentheses = nosingletable
-max_line_length = 98
+max_line_length = 105

.github/workflows/busted.yml

@@ -0,0 +1,37 @@
+name: Busted
+
+on: [push, pull_request]
+
+jobs:
+  busted:
+    strategy:
+      fail-fast: false
+      matrix:
+        lua_version: ["luajit-openresty", "luajit-2.1.0-beta3", "luajit-git"]
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup ‘lua’
+        uses: jkl1337/gh-actions-lua@master
+        with:
+          luaVersion: ${{ matrix.lua_version }}
+      - name: Setup ‘luarocks’
+        uses: jkl1337/gh-actions-luarocks@master
+      - name: Setup dependencies
+        run: |
+          luarocks install busted
+          luarocks install luacov-coveralls
+      - name: Build C library
+        run: |
+          luarocks make --no-install
+      - name: Run busted tests
+        run: busted -c -v
+      - name: Report test coverage
+        if: success()
+        continue-on-error: true
+        run: luacov-coveralls -e .luarocks -e spec
+        env:
+          COVERALLS_REPO_TOKEN: ${{ github.token }}

.gitignore

@@ -2,6 +2,9 @@
 /lua
 /lua_modules
 /.luarocks
+*.pch
+*.gch
 *.so
 *.o
 .cache/
+compile_commands.json

.luarc.json

@@ -8,6 +8,6 @@
     "lua_modules/share/lua/5.1/?.lua",
     "lua_modules/share/lua/5.1/?/init.lua"
   ],
-  "workspace.library": ["lua_modules/share/lua/5.1"],
+  "workspace.library": ["${3rd}/busted/library", "${3rd}/luassert/library"],
   "workspace.checkThirdParty": false
 }

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 John Luebs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Makefile

@@ -0,0 +1,93 @@
+-include config.mk
+
+CC := $(CROSS)gcc
+CP := cp
+RM := rm
+LIBFLAG := -shared
+LIB_EXT := so
+LUA_INCDIR := /usr/include
+
+SRCDIR := .
+
+OPTFLAG := -O2
+CCFLAGS += $(OPTFLAG) -fPIC -Wall -fvisibility=hidden -Wformat=2 -Wconversion -Wimplicit-fallthrough
+
+SANITIZE_FLAGS := -fstrict-flex-arrays -fsanitize=undefined -fsanitize=address
+LTO_FLAGS := -flto=auto
+
+ifdef SANITIZE
+	CCFLAGS += $(SANITIZE_FLAGS)
+endif
+ifdef LTO
+	CCFLAGS += $(LTO_FLAGS)
+endif
+
+override CPPFLAGS += -I$(SRCDIR) -I$(SRCDIR)/kiwi -I$(LUA_INCDIR)
+override CXXFLAGS += -std=c++14 -fno-rtti $(CCFLAGS)
+override CFLAGS += -std=c99 $(CCFLAGS)
+
+ifneq ($(filter %gcc,$(CC)),)
+  CXX := $(patsubst %gcc,%g++,$(CC))
+  PCH := ljkiwi.hpp.gch
+else
+  ifneq ($(filter %clang,$(CC)),)
+    CXX := $(patsubst %clang,%clang++,$(CC))
+    override CXXFLAGS += -pedantic -Wno-c99-extensions
+		PCH := ljkiwi.hpp.pch
+endif
+endif
+
+ifdef LUA
+LUA_VERSION ?= $(lastword $(shell $(LUA) -e "print(_VERSION)"))
+endif
+
+ifndef LUA_VERSION
+LJKIWI_CKIWI := 1
+else
+  ifeq ($(LUA_VERSION),5.1)
+    LJKIWI_CKIWI := 1
+  endif
+endif
+
+KIWI_LIB := AssocVector.h constraint.h debug.h errors.h expression.h kiwi.h maptype.h \
+  row.h shareddata.h solver.h solverimpl.h strength.h symbol.h symbolics.h term.h \
+  util.h variable.h version.h
+
+OBJS := luakiwi.o
+ifdef LJKIWI_CKIWI
+  OBJS += ckiwi.o
+endif
+
+vpath %.cpp $(SRCDIR)/ckiwi $(SRCDIR)/luakiwi
+vpath %.h $(SRCDIR)/ckiwi $(SRCDIR)/luakiwi $(SRCDIR)/kiwi/kiwi
+
+all: ljkiwi.$(LIB_EXT)
+
+install:
+	$(CP) -f ljkiwi.$(LIB_EXT) $(INST_LIBDIR)/ljkiwi.$(LIB_EXT)
+	$(CP) -f kiwi.lua $(INST_LUADIR)/kiwi.lua
+
+clean:
+	$(RM) -f ljkiwi.$(LIB_EXT) $(OBJS) $(PCH)
+
+
+ljkiwi.hpp.gch: $(KIWI_LIB)
+ckiwi.o: $(PCH) ckiwi.cpp ckiwi.h $(KIWI_LIB)
+luakiwi.o: $(PCH) luakiwi-int.h luacompat.h $(KIWI_LIB)
+
+ljkiwi.$(LIB_EXT): $(OBJS)
+	$(CXX) $(CCFLAGS) $(LIBFLAG) -o $@ $(OBJS)
+
+%.hpp.gch: %.hpp
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -x c++-header -o $@ $<
+
+%.hpp.pch: %.hpp
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -x c++-header -o $@ $<
+
+%.o: %.c
+	$(CC) $(CPPFLAGS) $(CFLAGS) -c -o $@ $<
+
+%.o: %.cpp
+	$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c -o $@ $<
+
+.PHONY: all install clean

README.md

@@ -0,0 +1,94 @@
+ljkiwi - Free LuaJIT FFI and Lua C API kiwi (Cassowary derived) constraint solver.
+
+[![CI](https://github.com/jkl1337/ljkiwi/actions/workflows/busted.yml/badge.svg)](https://github.com/jkl1337/ljkiwi/actions/workflows/busted.yml)
+[![Coverage Status](https://coveralls.io/repos/github/jkl1337/ljkiwi/badge.svg?branch=master)](https://coveralls.io/github/jkl1337/ljkiwi?branch=master)
+[![luarocks](https://img.shields.io/luarocks/v/jkl/kiwi)](https://luarocks.org/modules/jkl/kiwi)
+
+# Introduction
+
+Kiwi is a reasonably efficient C++ implementation of the Cassowary constraint solving algorithm. It is an implementation of the algorithm as described in the paper ["The Cassowary Linear Arithmetic Constraint Solving Algorithm"](http://www.cs.washington.edu/research/constraints/cassowary/techreports/cassowaryTR.pdf) by Greg J. Badros and Alan Borning. The Kiwi implementation is not based on the original C++ implementation, but is a ground-up reimplementation with performance 10x to 500x faster in typical use.
+Cassowary constraint solving is a technique that is particularly well suited to user interface layout. It is the algorithm Apple uses for iOS and OS X Auto Layout.
+
+There are a few Lua implementations or attempts. The SILE typesetting system has a pure Lua implementation of the original Cassowary code, which appears to be correct but is quite slow. There are two extant Lua ports of Kiwi, one that is based on a C rewrite of Kiwi. However testing of these was not encouraging with either segfaults or incorrect results.
+Since the C++ Kiwi library is well tested and widely used it was simpler to provide a LuaJIT FFI wrapper. There is also a Lua C API binding with support for 5.1 through 5.4.
+This package has no dependencies other than a supported C++14 compiler to compile the included Kiwi library and a small C wrapper.
+
+The Lua API has a pure Lua expression builder. There is of course some overhead to this, however in most cases expression building is infrequent and the underlying structures can be reused.
+
+The wrapper is quite close to the Kiwi C++/Python port with a few naming changes.
+
+## Example
+
+```lua
+local kiwi = require("kiwi")
+local Var = kiwi.Var
+
+local Button = setmetatable({}, {
+   __call = function(_, identifier)
+      return setmetatable({
+         left = Var(identifier .. " left"),
+         width = Var(identifier .. " width"),
+      }, {
+         __tostring = function(self)
+            return "Button(" .. self.left:value() .. ", " .. self.width:value() .. ")"
+         end,
+      })
+   end,
+})
+
+local b1 = Button("b1")
+local b2 = Button("b2")
+
+local left_edge = Var("left")
+local right_edge = Var("width")
+
+local STRONG = kiwi.Strength.STRONG
+
+-- stylua: ignore start
+local constraints = {
+   left_edge    :eq(0.0),
+   -- two buttons are the same width
+   b1.width     :eq(b2.width),
+   -- button1 starts 50 from the left margin
+   b1.left      :eq(left_edge + 50),
+   -- button2 ends 50 from the right margin
+   right_edge   :eq(b2.left + b2.width + 50),
+   -- button2 starts at least 100 from the end of button1. This is the "elastic" constraint
+   b2.left      :ge(b1.left + b1.width + 100),
+   -- button1 has a minimum width of 87
+   b1.width     :ge(87),
+   -- button1 has a preferred width of 87
+   b1.width     :eq(87, STRONG),
+   -- button2 has minimum width of 113
+   b2.width     :ge(113),
+   -- button2 has a preferred width of 113
+   b2.width     :eq(113, STRONG),
+}
+-- stylua: ignore end
+
+local solver = kiwi.Solver()
+
+for _, c in ipairs(constraints) do
+   solver:add_constraint(c)
+end
+
+solver:update_vars()
+
+print(b1) -- Button(50, 113)
+print(b2) -- Button(263, 113)
+print(left_edge:value()) -- 0
+print(right_edge:value()) -- 426
+
+solver:add_edit_var(right_edge, STRONG)
+solver:suggest_value(right_edge, 500)
+solver:update_vars()
+print(b1) -- Button(50, 113)
+print(b2) -- Button(337, 113)
+print(right_edge:value()) -- 500
+
+```
+
+In addition to the expression builder there is a convenience constraints submodule with: `pair_ratio`, `pair`, and `single` to allow efficient construction of the most common simple expression types for GUI layout.
+
+## Documentation
+WIP - However the API is fully annotated and will work with lua-language-server. Documentation can also be generated with lua-language-server.