From a2c2d141001cb090b1bec213195e8708a7093576 Mon Sep 17 00:00:00 2001 From: Justine Tunney Date: Thu, 18 Jun 2020 16:14:47 -0700 Subject: [PATCH] Add further clarity to example package --- Makefile | 3 ++- README.md | 2 +- examples/examples.mk | 4 +++- examples/package/lib/build.mk | 22 +++++++++++++--------- examples/package/lib/myasm.S | 14 ++++++++++++-- examples/package/lib/myprint.c | 9 +++++++++ 6 files changed, 40 insertions(+), 14 deletions(-) diff --git a/Makefile b/Makefile index 59211565..5e7a4e8a 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 a3050427..d165b1ff 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 458f13ab..2cd6e636 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 2e39419f..05b0d425 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 b7552c2f..c9358415 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 e254f365..6de2fa18 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); }