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)$ 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

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:~#