# Installation

1. Download the most recent release of `openscad_attachable_text3d` from https://github.com/jon-gilbert/openscad_attachable_text3d/releases/latest 
2. Unpack the zipfile or tarball. Inside will be a directory, named `openscad_attachable_text3d-0.8` (where `0.8` is the version of the release). Extract that folder to your OpenSCAD library directory
3. Rename that release directory from `openscad_attachable_text3d-0.8` to just `openscad_attachable_text3d`


## Required OpenSCAD Version

Using the `openscad_attachable_text3d` library requires OpenSCAD 2021.01 or later. Visit https://openscad.org/ for installation instructions.


## Requried External Libraries

### BOSL2

You'll need the Belfry OpenSCAD Library (v.2), authored by a number of contributors, and located at https://github.com/BelfrySCAD/BOSL2/

To download this library, follow the instructions provided at https://github.com/BelfrySCAD/BOSL2/#installation

### fontmetrics & fontmetricsdata

`openscad_attachable_text3d` requires the `fontmetrics` and `fontmetricsdata` SCAD libraries by [Alexander Pruss](https://www.thingiverse.com/arpruss).
They're licensed under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) and are available from  https://www.thingiverse.com/thing:3004457/files .

**Both of these libraries are redistributed within `openscad_attachable_text3d`, here.**

#### fontmetrics changes

The fontmetrics.scad library this project depends on has a minor bug in its library. It's easily rectified, as detailed below:

At line 27 of the `fontmetrics.scad` library, a function `_isString()` is defined that compares `v` with 
an empty string, `""`. This breaks under certain circumstances.  A more thorough, safer implementation 
is to use OpenSCAD's built-in `is_string()` function (available as of their 2019.05 release). You can make 
that change directly into `fontmetrics.scad` as such:

```
27c27
< function _isString(v) = v >= "";
---
> function _isString(v) = is_string(v);
```

**This release of `openscad_attachable_text3d` has the `_isString()` fix applied.**