Automated STL generation fails with certain libraries, Makefile documentation out of date

[phrxmd]

Describe the bug
The documentation on using make to autogenerate STLs is out of date. It uses use <base.scad>, which is broken when the file uses libraries that expect to be included, such as BOSL2. The Makefile example should use include <base.scad> instead.

To Reproduce
Steps to reproduce the behavior:

1. Use the minimal example file base.scad below that uses BOSL2
2. Use the Makefile from the documentation, add OPENSCADPATH that has BOSL2
3. Invoke make all

With older versions of OpenSCAD that works fine; with newer versions of OpenSCAD you get the following error:

> make all
echo -ne 'use <base.scad>\nmycube();' > mycube.scad
flatpak run --env=OPENSCADPATH=/my/library/path/lib org.openscad.OpenSCAD -m make -o mycube.stl -d mycube.stl.deps mycube.scad
WARNING: Ignoring unknown variable '$anchor_override' in file ../lib/BOSL2/attachments.scad, line 3047
WARNING: Ignoring unknown variable '$attach_to' in file ../lib/BOSL2/attachments.scad, line 3694
WARNING: Ignoring unknown variable '$tags_shown' in file ../lib/BOSL2/attachments.scad, line 4209
WARNING: Ignoring unknown variable '$tags_shown' in file ../lib/BOSL2/attachments.scad, line 4209
ERROR: Assertion '(is_list($tags_shown) || ($tags_shown == "ALL"))' failed in file ../lib/BOSL2/attachments.scad, line 4209
TRACE: called by '_is_shown' in file ../lib/BOSL2/attachments.scad, line 3070
TRACE: called by 'if' in file ../lib/BOSL2/attachments.scad, line 3070
TRACE: called by 'multmatrix' in file ../lib/BOSL2/attachments.scad, line 3061
TRACE: call of 'attachable(anchor = [0, 0, 0], spin = 0, orient = [0, 0, 1], size = [10, 10, 10], size2 = undef, shift = undef, r = undef, r1 = undef, r2 = undef, d = undef, d1 = undef, d2 = undef, l = undef, h = undef, vnf = undef, path = undef, region = undef, extent = true, cp = [0, 0, 0], offset = [0, 0, 0], anchors = [], two_d = false, axis = [0, 0, 1], override = undef, geom = ["prismoid", [10, 10, 10], [10, 10], [0, 0], [0, 0, 1], function(anchor) [undef, undef, undef], [0, 0, 0], [0, 0, 0], []], expose_tags = false, keep_color = false)' in file ../lib/BOSL2/attachments.scad, line 3038
TRACE: called by 'attachable' in file ../lib/BOSL2/shapes3d.scad, line 394
TRACE: called by 'if' in file ../lib/BOSL2/shapes3d.scad, line 350
TRACE: call of 'cuboid(size = [10, 10, 10], p1 = undef, p2 = undef, chamfer = undef, rounding = undef, edges = [[1, 1, 1, 1], [1, 1, 1, 1], [1, 1, 1, 1]], except = [], except_edges = undef, trimcorners = true, teardrop = false, anchor = [0, 0, 0], spin = 0, orient = [0, 0, 1])' in file ../lib/BOSL2/shapes3d.scad, line 207
TRACE: called by 'cuboid' in file base.scad, line 5
TRACE: call of 'mycube()' in file base.scad, line 3
TRACE: called by 'mycube' in file mycube.scad, line 2
Current top level object is empty.
make: *** [Makefile:17: mycube.stl] Fehler 1

Expected behavior
make all should generate useable STLs also with newer versions of OpenSCAD.

Code reproducing the issue
base.scad:

include <BOSL2/std.scad>

module mycube() // make me
{
  cuboid([10,10,10]);
}

Makefile is the example from the OpenSCAD User Manual, with the library path added:

# match "module foobar() { // `make` me"
TARGETS=$(shell sed '/^module [a-z0-9_-]*().*make..\?me.*$$/!d;s/module //;s/().*/.stl/' base.scad)

all: ${TARGETS}

# auto-generated .scad files with .deps make make re-build always. keeping the
# scad files solves this problem. (explanations are welcome.)
.SECONDARY: $(shell echo "${TARGETS}" | sed 's/\.stl/.scad/g')

# explicit wildcard expansion suppresses errors when no files are found
include $(wildcard *.deps)

%.scad:
	echo -ne 'use <base.scad>\n$*();' > $@

%.stl: %.scad
	flatpak run --env=OPENSCADPATH=/my/library/path/lib org.openscad.OpenSCAD -m make -o $@ -d $@.deps $<
	# OPENSCADPATH=/my/library/path/lib openscad -m make -o $@ -d $@.deps $<

Environment and Version info:

• OS: OpenSUSE Tumbleweed
• System: Intel PC 64-bit
• OpenSCAD Version: 2024.06.13 from Flathub Beta

Additional context
It works if you change the line starting with %.scad in the makefile to use include instead of use:

%.scad:
	echo -ne 'include <base.scad>\n$*();' > $@

The documentation should probably reflect this.

[kintel]

Not sure I understand why your change works. This sounds a bit like it's related to how BOSL is used, not about the makefile organization.

[nophead]

Looks like the breaking change to how $variables work that breaks my libraries as well.

[jordanbrown0]

Right now, that Makefile is probably best regarded as an example, not the one-and-only way to solve the problem.

include <base.scad> is probably a better answer, because it effectively means that the invocation of the module is appended to the main .scad file, without bringing in any of the "interesting" semantics of use. Better, however, would be to use the fact that -D can run arbitrary commands to invoke the module without the need for a temporary .scad file.