add README

diff --git a/README.mdwn b/README.mdwn
new file mode 100644 (file)
index 0000000..6ac548a
--- /dev/null
+++ b/README.mdwn
@@ -0,0 +1,65 @@
+# Libre-SOC Reproducible Build Scripts
+
+This repository contains the Libre-SOC "reproducible builds" scripts.
+Initially begun as a way to ensure that coriolis2 VLSI ASIC layouts
+were reproducible, they've turned into an easy way for developers to
+get started.  
+
+All packages are installed within a baseline debian/10 debootstrapped
+schroot.  For reproducible builds, you have to pick an OS, and debian/10
+is good enough
+
+Prerequisites:
+
+* Strongly recommended that you install a Host OS of Debian.
+* Confirmed working but not supported: ubuntu
+* Also confirmed working with a caveat on X11: archlinux,
+  (which happens to have a port of debootstrap)
+
+Installs (at recent but usually specific - reproducible - versions):
+
+* coriolis2
+* yosys
+* symbiyosys, z3 solver, yices, sby
+* ghdl
+* yosys-ghdl
+* nextpnr-ecp5
+* nextpnr-xilinx
+* symbiflow
+* nmigen (a Registered Trademark of M-Labs)
+* verilator
+* icarus verilog
+* cocotb
+* a ton of FPGA loader tools, dfu-util, openFPGALoader, ecpprog,
+  fujprog, and associated udev.d rules files.
+
+Note: we don't use conda.  we don't use docker.
+
+# Installation Notes
+
+During their development, each install script had notes taken which,
+if followed carefully, should result in the replication of the script.
+These notes can be found here:
+
+* <https://libre-soc.org/HDL_workflow/>
+* <https://libre-soc.org/HDL_workflow/coriolis2/>
+* <https://libre-soc.org/HDL_workflow/nextpnr/>
+* <https://libre-soc.org/HDL_workflow/nextpnr-xilinx/>
+* <https://libre-soc.org/HDL_workflow/verilator/>
+* <https://libre-soc.org/HDL_workflow/ghdl/>
+* <https://libre-soc.org/HDL_workflow/iverilog/>
+* <https://libre-soc.org/HDL_workflow/cocotb/>
+* <https://libre-soc.org/HDL_workflow/symbiflow/>
+* <https://libre-soc.org/HDL_workflow/fpga-boot-loaders-progs/>
+
+# Contact details
+
+Any questions, improvements, bug-fixes or patches, most welcome:
+please join Libera.Chat IRC #libre-soc, or join the mailing list:
+<https://lists.libre-soc.org/mailman/listinfo/libre-soc-dev>
+
+# Charter
+
+Covered by the Libre-SOC Charter <https://libre-soc.org/charter/discussion/>
+we particularly welcome appropriate Dilbert Cartoons illustrating the
+antithetical polar opposite.