1# How To Compile Pikchr 2 3## Overview 4 5 * Primary source file: "`pikchr.y`" 6 * Process "`pikchr.y`" using Lemon (sources provided in tree) 7 to create "`pikchr.c`" 8 * Compile "`pikchr.c`" into an object file, or add the 9 "`-DPIKCHR_SHELL`" command-line option to generate a stand-alone 10 executable. 11 * A pre-processed "[`pikchr.c`][src]" source file is stored in the 12 source tree for the convenience of integrators who do not want to 13 figure out how to build and run Lemon. 14 15[src]: /file/pikchr.c 16 17~~~ pikchr 18 filewid *= 1.2 19 Src: file "pikchr.y"; move 20 LemonSrc: file "lemon.c"; move 21 Lempar: file "lempar.c"; move 22 arrow down from LemonSrc.s 23 CC1: oval "C-Compiler" ht 50% 24 arrow " generates" ljust above 25 Lemon: oval "lemon" ht 50% 26 arrow from Src chop down until even with CC1 \ 27 then to Lemon.nw rad 10px 28 "Pikchr source " rjust "code input " rjust \ 29 at 2nd vertex of previous 30 arrow from Lempar chop down until even with CC1 \ 31 then to Lemon.ne rad 10px 32 " parser template" ljust " resource file" ljust \ 33 at 2nd vertex of previous 34 PikSrc: file "pikchr.c" with .n at lineht below Lemon.s 35 arrow from Lemon to PikSrc chop 36 arrow down from PikSrc.s 37 CC2: oval "C-Compiler" ht 50% 38 arrow 39 Out: file "pikchr.o" "or" "pikchr.exe" wid 110% 40 spline <- from 1mm west of Src.w go 60% heading 250 \ 41 then go 40% heading 45 then go 60% heading 250 \ 42 thin color gray 43 box invis "Canonical" ljust small "Source code" ljust small fit \ 44 with .e at end of last spline width 90% 45 spline <- from 1mm west of PikSrc.w go 60% heading 250 \ 46 then go 40% heading 45 then go 60% heading 250 \ 47 thin color gray 48 box invis "Preprocessed" ljust small \ 49 "C-code" ljust small "also in-tree" ljust small fit \ 50 with .e at end of last spline width 90% 51~~~ 52 53## Details: 54 55The source code for Pikchr is in the file named "`pikchr.y`". As 56the ".y" suffix implies, this file is a grammar specification intended 57as input to the yacc-like LALR(1) parser generator program 58"[Lemon][lemon]". Even though "pikchr.y" is technically a Lemon 59grammar file, it consists of mostly C-code and only 6% grammar. 60 61Running the command: 62 63~~~~ 64 lemon pikchr.y 65~~~~ 66 67Generates "`pikchr.c`" as an output file. (Lemon generates a couple 68of other output files that can be ignored for this project.) The 69"pikchr.c" file is pure C code ready to be compiled into the final 70application. It can be compiled by itself with the 71"-DPIKCHR_SHELL" command-line option to generate a standalone program 72that reads Pikchr scripts and emits HTML with embedded SVG. Or 73it can be integrated into a larger application which invokes the 74"`pikchr()`" C-API to do conversions from Pikchr to SVG. 75 76As the Lemon tool is not widely deployed, the source code for 77Lemon is included in the Pikchr source tree for convenience. 78Compile the "`lemon.c`" source program into an executable using 79any ordinary C-compiler. 80 81When the lemon executable runs, it looks for the "`lempar.c`" template 82in the working directory. The "`lempar.c`" template is also included 83in the Pikchr source repository for convenience. 84 85[lemon]: https://www.sqlite.org/lemon.html 86 87## Preprocessed Sources Available For Download. 88 89As a convenience to integrators, the pre-processed "`pikchr.c`" C-code 90file is normally checked into the Pikchr source tree. Hence, to build 91Pikchr into another system, just grab a copy of that one file and add 92it to the project. 93