# Dev setup scripts
+Setting up the dependencies and repositories for Libre-SOC is big enough
+that it is just much easier to do in an automated fashion. Follow these
+steps after making sure that you review the scripts line by line because
+they run as root and it is your responsibility to check them, not ours.
+
+Note the reason for entering the chroot as a user (not root) and
+then running sudo bash again is due to this procedure setting the
+SUDO_USER environment, on which the scripts critically rely. Also:
+the dev-env-setup repository is cloned twice, once to get the chroot
+script and a second time to use scripts *inside* the chroot. Feel free
+to simply copy the repository into the chroot to save bandwidth.
+
+**no you do not need to blow away your system and install debian 10 native**
+you can e.g. use debian/11 at the "host" level and some people have managed
+to use archlinux but you are **on your own if you do so, and should only
+consider the option of using your own preferred host OS if you are an
+advanced expert**. We do **NOT** provide "personal end-user support"
+for Host OS problems.
+
+Note: these scripts assume that you are using debian/10 and that you
+understand and accept why we have standardised on that as an OS
+(reproduceability and minimising "support"). If you use anything
+different it risks creating non-reproducible HDL. It's not about
+"what's the favurite OS", it's about making sure that two developers
+can produce the **exact** same GDS-II files, which is kinda important
+if you are going to drop USD 16 million on 7nm Mask Charges.
+
$ git clone https://git.libre-soc.org/git/dev-env-setup.git
$ cd dev-env-setup
$ sudo bash
+ (optional: # export CHROOT_DEBIAN_MIRROR=http://ftp.<mirror>.debian.org/debian)
# ./mk-deb-chroot libresoc
+ # ./cp-scripts-to-chroot libresoc # copies dev-env-setup to chroot
# exit
$ schroot -c libresoc
- (libresoc)$ git clone https://git.libre-soc.org/git/dev-env-setup.git
- (libresoc)$ cd dev-env-setup
(libresoc)$ sudo bash
(libresoc)# ./install-hdl-apt-reqs
+ (libresoc)# ./hdl-tools-yosys
(libresoc)# ./hdl-dev-repos
+ (libresoc)# ./ppc64-gdb-gcc # needed for compiling unit tests
+ (libresoc)# ./binutils-gdb-install # needed for binutils-svp64
(libresoc)# exit
(libresoc)$
-https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=hdl-dev-repos;hb=HEAD
+<https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=hdl-dev-repos;hb=HEAD>
+
+Additional scripts in the dev-env-setup repository will install yosys,
+verilator, coriolis2, ghdl, gdb and so on: from the above it is pretty
+straightforward and obvious to work out what to do (just run them).
+There is an accompanying walkthrough video which goes through the above
+<https://m.youtube.com/watch?v=1-4eJKTNrEk> and includes running some
+unit tests, explaining some of the background, and also files some bugs.
+
+**You are now done, you need only read the rest below if interested
+to see how we made the above scripts**
+
+=======
+=======
+=======
+=======
+=======
+
+# Notes about Script "mk-deb-chroot"
+
+This section is developer-notes **only** it documents the
+process by which mk-deb-chroot was established and explains
+its decisions and effect.
+
+The script sets up an schroot debootstrap jail with debian 10.
+This chroot can then be used for nmigen, coriolis, or any other development.
+These instructions are based on information taken from here:
+<https://www.debian.org/releases/stretch/amd64/apds03.html.en>
+
+The chroot name for this section is assumed to be "libresoc"
+
+In advance, on the host system, edit /etc/fstab and add mount points:
+
+(edit: personally I prefer using mount --bind points. however if doing
+that then after a reboot the chroot will lose the bind mountpoints
+and the commands need to be re-run, without which the chroot is
+unusable)
+
+ /dev /home/chroot/libresoc/dev none bind 0 0
+ /dev/pts /home/chroot/libresoc/dev/pts none bind 0 0
+ /proc /home/chroot/libresoc/proc none bind 0 0
+ /sys /home/chroot/libresoc/sys none bind 0 0
+ /tmp /home/chroot/libresoc/tmp none bind 0 0
+
+Then run these commands:
+
+ sudo bash
+ apt-get install debootstrap schroot
+ mkdir /opt/chroot/libresoc
+ /usr/sbin/debootstrap buster !$ http://ftp.us.debian.org/debian
+ mount /home/chroot/libresoc/dev
+ mount /home/chroot/libresoc/dev/pts
+ mount /home/chroot/libresoc/proc
+ mount /home/chroot/libresoc/sys
+ mount /home/chroot/libresoc/tmp
+ echo "libresoc" > /home/chroot/libresoc/etc/debian_chroot
+
+To do some preparation (users):
+
+ chroot -c libresoc /bin/bash
+ adduser {yourpreferredusername}
+
+It is best to make the username the same as the first user that
+was added during the *main* (non-chroot) debian install, so that
+uid 1000 matches between both main and chroot. You can check
+this by looking at /etc/passwd as root, or by typing "id".
+
+ lkcl@fizzy:~$ id
+ uid=1000(lkcl) gid=1000(lkcl) groups=1000(lkcl),5(tty),....
+
+Alternatively, /etc/passwd and /etc/group may
+be mount-bound as well as /home however if you later forget you did
+this and decide to delete the chroot, you will delete the entire /home
+of your main system, as well as /etc/passwd.
+
+You may wish to follow some of the other things such as configuring apt,
+locales and keyboard, from the above-linked debian-admin HOWTO.
+
+bootloader, kernel, ssh access, are unnecessary. Do run "apt clean"
+to clear out /var/cache/apt/archives in the chroot.
+
+
+
+
+Create an schroot file section for the libresoc chroot by
+editing /etc/schroot/schroot.conf:
+
+ [libresoc]
+ description=Debian Buster for Coriolis
+ directory=/home/chroot/libresoc
+ groups=sbuild-security,lkcl,users
+
+Now as an *ordinary* user - not as root - you may type:
+
+ lkcl@fizzy:~$ schroot -c libresoc
+
+and, due to the contents of /etc/debian\_chroot, and that you were in
+fact logged in as uid 1000 and did in fact add a user to the chroot
+as uid 1000, the prompt should become:
+
+ (libresoc)lkcl@fizzy:~$
+
+If however you need to run as root, then from outside the chroot,
+as *root*, you run this:
+
+ lkcl@fizzy:~# schroot -c libresoc
+
+and you will see this as a result:
+
+ (libresoc)lkcl@fizzy:~#
+