diff --git a/Makefile b/Makefile index 59211565d..5e7a4e8a9 100644 --- a/Makefile +++ b/Makefile @@ -193,7 +193,8 @@ include test/dsp/core/test.mk include test/dsp/scale/test.mk include test/dsp/tty/test.mk include test/dsp/test.mk -include third_party/make/build.mk +include examples/package/lib/build.mk +include examples/package/build.mk #-φ-examples/package/new.sh include test/test.mk diff --git a/README.md b/README.md index a30504277..d165b1ffb 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ by typing `C-c C-h` with the cursor over a symbol. Please install these: emacs # for power and glory! See [tool/emacs/cosmo-stuff.el] for further details. Further note that -this codebase might seem to have an usual number of include statements +this codebase might seem to have unusual numbers of include statements quoted and vendored code, but that's actually why the tools work since it gives them easy perfect knowledge of what exists, thus performance. diff --git a/examples/examples.mk b/examples/examples.mk index 458f13abc..2cd6e636c 100644 --- a/examples/examples.mk +++ b/examples/examples.mk @@ -115,4 +115,6 @@ o/$(MODE)/examples/hellojs.com.dbg: \ @$(APELINK) .PHONY: o/$(MODE)/examples -o/$(MODE)/examples: $(EXAMPLES_BINS) +o/$(MODE)/examples: \ + o/$(MODE)/examples/package \ + $(EXAMPLES_BINS) diff --git a/examples/package/lib/build.mk b/examples/package/lib/build.mk index 2e39419fe..05b0d425f 100644 --- a/examples/package/lib/build.mk +++ b/examples/package/lib/build.mk @@ -20,7 +20,7 @@ # EXAMPLE # # make o//examples/package/lib # build library w/ sanity checks -# at t o//examples/package/lib/lib.a +# ar t o//examples/package/lib/lib.a # # AUTHORS # @@ -28,19 +28,22 @@ PKGS += EXAMPLES_PACKAGE_LIB -# Declares build package. -# Other packages may list this variable in their deps list. -# Please note package relationships aren't allowed to be cyclic. +# Declares package i.e. library w/ transitive dependencies. +# We define packages as a thing that lumps similar sources. +# It's needed, so linkage can have a higher level overview. +# Mostly due to there being over 9,000 objects in the repo. EXAMPLES_PACKAGE_LIB = \ $(EXAMPLES_PACKAGE_LIB_A_DEPS) \ $(EXAMPLES_PACKAGE_LIB_A) -# While build configs might seem somewhat complicated but rest -# assured they're mostly maintainence free, thanks to wildcard -EXAMPLES_PACKAGE_LIB_A_FILES := $(wildcard examples/package/lib/*) -EXAMPLES_PACKAGE_LIB_ARTIFACTS += EXAMPLES_PACKAGE_LIB_A -EXAMPLES_PACKAGE_LIB_A_HDRS = $(filter %.h,$(EXAMPLES_PACKAGE_LIB_A_FILES)) +# Declares library w/o transitive dependencies. EXAMPLES_PACKAGE_LIB_A = o/$(MODE)/examples/package/lib/lib.a +EXAMPLES_PACKAGE_LIB_ARTIFACTS += EXAMPLES_PACKAGE_LIB_A + +# Build configs might seem somewhat complicated. Rest assured they're +# mostly maintainence free. That's largely thanks to how we wildcard. +EXAMPLES_PACKAGE_LIB_A_FILES := $(wildcard examples/package/lib/*) +EXAMPLES_PACKAGE_LIB_A_HDRS = $(filter %.h,$(EXAMPLES_PACKAGE_LIB_A_FILES)) # Define sets of source files without needing further iops. EXAMPLES_PACKAGE_LIB_A_SRCS_S = \ @@ -57,6 +60,7 @@ EXAMPLES_PACKAGE_LIB_A_OBJS = \ $(EXAMPLES_PACKAGE_LIB_A_SRCS_C:%.c=o/$(MODE)/%.o) \ $(EXAMPLES_PACKAGE_LIB_A_SRCS:%=o/$(MODE)/%.zip.o) +# Does the two most important things for C/C++ code sustainability. # 1. Guarantees each header builds, i.e. includes symbols it needs. # 2. Guarantees transitive closure of packages is directed acyclic. EXAMPLES_PACKAGE_LIB_A_CHECKS = \ diff --git a/examples/package/lib/myasm.S b/examples/package/lib/myasm.S index b7552c2f2..c93584151 100644 --- a/examples/package/lib/myasm.S +++ b/examples/package/lib/myasm.S @@ -1,6 +1,16 @@ #include "libc/macros.h" -MyAsm: .leafprologue +/ Example assembly function. +/ +/ @note param agnostic +/ @note we love stack frames +/ easiest way to do backtraces +/ somehow they usually make code faster +/ it's convention for keeping stack 16-byte aligned +/ cpus still devote much to pushing & popping b/c i386 +MyAsm: push %rbp + mov %rsp,%rbp call MyPrint2 - .leafepilogue + pop %rbp + ret .endfn MyAsm,globl diff --git a/examples/package/lib/myprint.c b/examples/package/lib/myprint.c index e254f3657..6de2fa183 100644 --- a/examples/package/lib/myprint.c +++ b/examples/package/lib/myprint.c @@ -1,10 +1,19 @@ #include "examples/package/lib/myprint.h" #include "libc/stdio/stdio.h" +/** + * Calls MyPrint2() indirected via assembly function. + */ void MyPrint(const char *s) { MyAsm(s); } +/** + * Prints string to output. + * + * @param s is null-terminated c string usually having \n + * @see printf() which has domain-specific language + */ void MyPrint2(const char *s) { fputs(s, stdout); }