6.3.4.2 Custom module backends

Let’s create some new custom backends. Here is how you can do it.

Create a file named custom-backend.scm with the following contents:

(define-module (backend custom-backend)
  #:use-module (netlist schematic)
  #:use-module (netlist schematic toplevel)
  #:export (custom-backend))

(define (custom-backend)
  (display (schematic-components (toplevel-schematic))))

Put the file into the directory ~/.local/share/lepton-eda/scheme/backend. Now, lepton-netlist should report its name if you launch it with the option --list-backends:

$ lepton-netlist --list-backends
...
custom-backend
...

Run it:

$ lepton-netlist -g custom-backend my-schematic.sch

The output in the file output.net in the current working directory may look as follows:

(#<geda-schematic-component 54> #<geda-schematic-component 90>)

You can use pre-load (-l) and post-load (-m) scripts along with legacy backends to maybe redefine some code or re-use it. Pre- and post-loading functionality is not used for module backends. Instead of loading a backend and then redefining its functions using -m, you can define a new module backend and redefine or re-use the functions in it. Pre-loading by the option -l can be changed the same way, just define a module and use its functions in another module. If you want to use the code from a legacy backend, just primitive-load its file. Here are several examples.

Let’s suppose that you have a legacy backend named gnet-legacy.scm and want to re-use its main function legacy() in your code. It may live in any directory defined in lepton-netlist’s %load-path. To check the contents of %load-path you can issue the following command:

lepton-netlist -c '(display %load-path)'

or just open lepton-netlist in interactive-mode

enter %load-path and hit RET.

The contents of your backend can then be changed to something like this:

(define-module (backend custom-backend)
  #:use-module (netlist schematic)
  #:use-module (netlist schematic toplevel)
  #:export (custom-backend))

(primitive-load "gnet-legacy.scm")  ; <= new line

(define (custom-backend)
  (display (legacy))  ; <= new line
  (display (schematic-components (toplevel-schematic))))

You don’t have to put the file into a load path known for lepton-netlist. To use your file from any other directory, just specify its absolute path in primitive-load, e.g. (primitive-load "/tmp/gnet-legacy.scm").

If you want to pre-load a module backend and use its contents, just import it in the code and use its exported function.

Supposed you have a backend file print-config.scm in your user backend directory with the following contents:

(define-module (backend print-config)
  #:use-module (netlist config)
  #:export (print-config))

(define (print-config)
  (print-netlist-config))

and want to use it in the above custom backend, you just edit the custom backend as follows:

(define-module (backend custom-backend)
  #:use-module (netlist schematic)
  #:use-module (netlist schematic toplevel)
  #:use-module (backend print-config)  ; <= new line
  #:export (custom-backend))

(define (custom-backend)
  (print-config)  ; <= new line
  (display (schematic-components (toplevel-schematic))))

Post-loading function is no longer necessary, either. If you want to add some functionality without modifying an original backend code, just add a new backend.

For instance, you want to output some additional, maybe debugging, information before and after the output of the function custom-backend(). What you need is just a new backend module in your user backend directory which re-uses the function. To accomplish that, you could make a backend file with the following contents:

(define-module (backend add-headers-and-footers)
  #:use-module (backend custom-backend)
  #:export (add-headers-and-footers))

(define (add-headers-and-footers)
  (display "Those are schematic components:\n")  ; <= header
  (custom-backend)  ; <= main backend output
  (display "That's all folks!")  ; <= footer)

Name the file add-headers-and-footers.scm and put it into one of your backend directories, then run:

$ lepton-netlist -g add-headers-and-footers my-schematic.sch

and you’re done, congrats!