HDL_workflow/devscripts.mdwn

   1 # Dev setup scripts
   2
   3 Setting up the dependencies and repositories for Libre-SOC is big enough
   4 that it is just much easier to do in an automated fashion.  Follow these
   5 steps after making sure that you review the scripts line by line because
   6 they run as root and it is your responsibility to check them, not ours.
   7
   8 Note the reason for entering the chroot as a user (not root) and
   9 then running sudo bash again is due to this procedure setting the
  10 SUDO_USER environment, on which the scripts critically rely.  Also:
  11 the dev-env-setup repository is cloned twice, once to get the chroot
  12 script and a second time to use scripts *inside* the chroot. Feel free
  13 to simply copy the repository into the chroot to save bandwidth.
  14
  15 Note: these scripts assume that you are using debian/10 and that you
  16 understand and accept why we have standardised on that as an OS
  17 (reproduceability and minimising "support").  If you use anything
  18 different it risks creating non-reproducible HDL. It's not about
  19 "what's the favurite OS", it's about making sure that two developers
  20 can produce the **exact** same GDS-II files.
  21
  22     $ git clone https://git.libre-soc.org/git/dev-env-setup.git
  23     $ cd dev-env-setup
  24     $ sudo bash
  25     # ./mk-deb-chroot libresoc
  26     # exit
  27     $ schroot -c libresoc
  28     (libresoc)$ git clone https://git.libre-soc.org/git/dev-env-setup.git
  29     (libresoc)$ cd dev-env-setup
  30     (libresoc)$ sudo bash
  31     (libresoc)# ./install-hdl-apt-reqs
  32     (libresoc)# ./hdl-dev-repos
  33     (libresoc)# ./ppc64-gdb-gcc           # needed for compiling unit tests
  34     (libresoc)# exit
  35     (libresoc)$
  36
  37 <https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=hdl-dev-repos;hb=HEAD>
  38
  39 Additional scripts in the dev-env-setup repository will install yosys,
  40 verilator, coriolis2, ghdl, gdb and so on: from the above it is pretty
  41 straightforward and obvious to work out what to do (just run them).
  42 There is an accompanying walkthrough video which goes through the above
  43 <https://m.youtube.com/watch?v=1-4eJKTNrEk> and includes running some
  44 unit tests, explaining some of the background, and also files some bugs.
  45
  46 # Notes about Script "mk-deb-chroot"
  47
  48 The script sets up an schroot debootstrap jail with debian 10.
  49 This chroot can then be used for nmigen, coriolis, or any other development.
  50 These instructions are based on information taken from here:
  51 <https://www.debian.org/releases/stretch/amd64/apds03.html.en>
  52
  53 The chroot name for this section is assumed to be "libresoc"
  54
  55 In advance, on the host system, edit /etc/fstab and add mount points:
  56
  57 (edit: personally I prefer using mount --bind points.  however if doing
  58 that then after a reboot the chroot will lose the bind mountpoints
  59 and the commands need to be re-run, without which the chroot is
  60 unusable)
  61
  62     /dev    /home/chroot/libresoc/dev   none    bind    0   0
  63     /dev/pts /home/chroot/libresoc/dev/pts  none    bind    0   0
  64     /proc   /home/chroot/libresoc/proc  none    bind    0   0
  65     /sys    /home/chroot/libresoc/sys   none    bind    0   0
  66     /tmp    /home/chroot/libresoc/tmp   none    bind    0   0
  67
  68 Then run these commands:
  69
  70     sudo bash
  71     apt-get install debootstrap schroot
  72     mkdir /opt/chroot/libresoc
  73     /usr/sbin/debootstrap buster !$ http://ftp.us.debian.org/debian
  74     mount /home/chroot/libresoc/dev
  75     mount /home/chroot/libresoc/dev/pts
  76     mount   /home/chroot/libresoc/proc
  77     mount   /home/chroot/libresoc/sys
  78     mount   /home/chroot/libresoc/tmp
  79     echo "libresoc" > /home/chroot/libresoc/etc/debian_chroot
  80
  81 To do some preparation (users):
  82
  83     chroot -c libresoc /bin/bash
  84     adduser {yourpreferredusername}
  85
  86 It is best to make the username the same as the first user that
  87 was added during the *main* (non-chroot) debian install, so that
  88 uid 1000 matches between both main and chroot.  You can check
  89 this by looking at /etc/passwd as root, or by typing "id".
  90
  91     lkcl@fizzy:~$ id
  92     uid=1000(lkcl) gid=1000(lkcl) groups=1000(lkcl),5(tty),....
  93
  94 Alternatively, /etc/passwd and /etc/group may
  95 be mount-bound as well as /home however if you later forget you did
  96 this and decide to delete the chroot, you will delete the entire /home
  97 of your main system, as well as /etc/passwd.
  98
  99 You may wish to follow some of the other things such as configuring apt,
 100 locales and keyboard, from the above-linked debian-admin HOWTO.
 101
 102 bootloader, kernel, ssh access, are unnecessary. Do run "apt clean"
 103 to clear out /var/cache/apt/archives in the chroot.
 104
 105
 106
 107
 108 Create an schroot file section for the libresoc chroot by
 109 editing /etc/schroot/schroot.conf:
 110
 111     [libresoc]
 112     description=Debian Buster for Coriolis
 113     directory=/home/chroot/libresoc
 114     groups=sbuild-security,lkcl,users
 115
 116 Now as an *ordinary* user - not as root - you may type:
 117
 118     lkcl@fizzy:~$ schroot -c libresoc
 119
 120 and, due to the contents of /etc/debian\_chroot, and that you were in
 121 fact logged in as uid 1000 and did in fact add a user to the chroot
 122 as uid 1000, the prompt should become:
 123
 124     (libresoc)lkcl@fizzy:~$
 125
 126 If however you need to run as root, then from outside the chroot,
 127 as *root*, you run this:
 128
 129     lkcl@fizzy:~# schroot -c libresoc
 130
 131 and you will see this as a result:
 132
 133     (libresoc)lkcl@fizzy:~#