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 **no you do not need to blow away your system and install debian 10 native**
  16 you can e.g. use debian/11 at the "host" level and some people have managed
  17 to use archlinux but you are **on your own if you do so, and should only
  18 consider the option of using your own preferred host OS if you are an
  19 advanced expert**.  We do **NOT** provide "personal end-user support"
  20 for Host OS problems.
  21
  22 Note: these scripts assume that you are using debian/10 and that you
  23 understand and accept why we have standardised on that as an OS
  24 (reproduceability and minimising "support").  If you use anything
  25 different it risks creating non-reproducible HDL. It's not about
  26 "what's the favurite OS", it's about making sure that two developers
  27 can produce the **exact** same GDS-II files, which is kinda important
  28 if you are going to drop USD 16 million on 7nm Mask Charges.
  29
  30     $ git clone https://git.libre-soc.org/git/dev-env-setup.git
  31     $ cd dev-env-setup
  32     $ sudo bash
  33     (optional: # export CHROOT_DEBIAN_MIRROR=http://ftp.<mirror>.debian.org/debian)
  34     # ./mk-deb-chroot libresoc
  35     # ./cp-scripts-to-chroot libresoc # copies dev-env-setup to chroot
  36     # exit
  37     $ schroot -c libresoc
  38     (libresoc)$ sudo bash
  39     (libresoc)# ./install-hdl-apt-reqs
  40     (libresoc)# ./hdl-tools-yosys
  41     (libresoc)# ./hdl-dev-repos
  42     (libresoc)# ./ppc64-gdb-gcc           # needed for compiling unit tests
  43     (libresoc)# ./binutils-gdb-install    # needed for binutils-svp64
  44     (libresoc)# exit
  45     (libresoc)$
  46
  47 <https://git.libre-soc.org/?p=dev-env-setup.git;a=blob;f=hdl-dev-repos;hb=HEAD>
  48
  49 Additional scripts in the dev-env-setup repository will install yosys,
  50 verilator, coriolis2, ghdl, gdb and so on: from the above it is pretty
  51 straightforward and obvious to work out what to do (just run them).
  52 There is an accompanying walkthrough video which goes through the above
  53 <https://m.youtube.com/watch?v=1-4eJKTNrEk> and includes running some
  54 unit tests, explaining some of the background, and also files some bugs.
  55
  56 **You are now done, you need only read the rest below if interested
  57 to see how we made the above scripts**
  58
  59 =======
  60 =======
  61 =======
  62 =======
  63 =======
  64
  65 # Notes about Script "mk-deb-chroot"
  66
  67 This section is developer-notes **only** it documents the
  68 process by which mk-deb-chroot was established and explains
  69 its decisions and effect.
  70
  71 The script sets up an schroot debootstrap jail with debian 10.
  72 This chroot can then be used for nmigen, coriolis, or any other development.
  73 These instructions are based on information taken from here:
  74 <https://www.debian.org/releases/stretch/amd64/apds03.html.en>
  75
  76 The chroot name for this section is assumed to be "libresoc"
  77
  78 In advance, on the host system, edit /etc/fstab and add mount points:
  79
  80 (edit: personally I prefer using mount --bind points.  however if doing
  81 that then after a reboot the chroot will lose the bind mountpoints
  82 and the commands need to be re-run, without which the chroot is
  83 unusable)
  84
  85     /dev    /home/chroot/libresoc/dev   none    bind    0   0
  86     /dev/pts /home/chroot/libresoc/dev/pts  none    bind    0   0
  87     /proc   /home/chroot/libresoc/proc  none    bind    0   0
  88     /sys    /home/chroot/libresoc/sys   none    bind    0   0
  89     /tmp    /home/chroot/libresoc/tmp   none    bind    0   0
  90
  91 Then run these commands:
  92
  93     sudo bash
  94     apt-get install debootstrap schroot
  95     mkdir /opt/chroot/libresoc
  96     /usr/sbin/debootstrap buster !$ http://ftp.us.debian.org/debian
  97     mount /home/chroot/libresoc/dev
  98     mount /home/chroot/libresoc/dev/pts
  99     mount   /home/chroot/libresoc/proc
 100     mount   /home/chroot/libresoc/sys
 101     mount   /home/chroot/libresoc/tmp
 102     echo "libresoc" > /home/chroot/libresoc/etc/debian_chroot
 103
 104 To do some preparation (users):
 105
 106     chroot -c libresoc /bin/bash
 107     adduser {yourpreferredusername}
 108
 109 It is best to make the username the same as the first user that
 110 was added during the *main* (non-chroot) debian install, so that
 111 uid 1000 matches between both main and chroot.  You can check
 112 this by looking at /etc/passwd as root, or by typing "id".
 113
 114     lkcl@fizzy:~$ id
 115     uid=1000(lkcl) gid=1000(lkcl) groups=1000(lkcl),5(tty),....
 116
 117 Alternatively, /etc/passwd and /etc/group may
 118 be mount-bound as well as /home however if you later forget you did
 119 this and decide to delete the chroot, you will delete the entire /home
 120 of your main system, as well as /etc/passwd.
 121
 122 You may wish to follow some of the other things such as configuring apt,
 123 locales and keyboard, from the above-linked debian-admin HOWTO.
 124
 125 bootloader, kernel, ssh access, are unnecessary. Do run "apt clean"
 126 to clear out /var/cache/apt/archives in the chroot.
 127
 128
 129
 130
 131 Create an schroot file section for the libresoc chroot by
 132 editing /etc/schroot/schroot.conf:
 133
 134     [libresoc]
 135     description=Debian Buster for Coriolis
 136     directory=/home/chroot/libresoc
 137     groups=sbuild-security,lkcl,users
 138
 139 Now as an *ordinary* user - not as root - you may type:
 140
 141     lkcl@fizzy:~$ schroot -c libresoc
 142
 143 and, due to the contents of /etc/debian\_chroot, and that you were in
 144 fact logged in as uid 1000 and did in fact add a user to the chroot
 145 as uid 1000, the prompt should become:
 146
 147     (libresoc)lkcl@fizzy:~$
 148
 149 If however you need to run as root, then from outside the chroot,
 150 as *root*, you run this:
 151
 152     lkcl@fizzy:~# schroot -c libresoc
 153
 154 and you will see this as a result:
 155
 156     (libresoc)lkcl@fizzy:~#
 157