r00t2/bdisk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity
f4f131890d
bdisk/docs/manual/user/GETTING_STARTED.adoc

5.5 KiB
Raw Blame History

Getting Started

Downloading

If it isn’t in your distro’s repositories (It is in Arch’s AUR! Both tagged release and git master.), you can still easily get rolling. Simply visit the project’s source code web interface and download a tarball under the Download column:

cgit

If you know the tag of the commit you want, you can use curl:

curl -sL https://git.square-r00t.net/BDisk/snapshot/BDisk-4.0.0.tar.xz | tar -xf -

or wget:

wget -O - https://git.square-r00t.net/BDisk/snapshot/BDisk-3.11.tar.xz | tar -xf -

You can use https://git.square-r00t.net/BDisk/snapshot/BDisk-master.tar.xz for the URL if you want the latest working version. If you want a snapshot of a specific commit, you can use e.g. https://git.square-r00t.net/BDisk/snapshot/BDisk-5ac510762ce00eef213957825de0e6d07186e7f8.tar.xz and so on.

Alternatively, you can use git. Git most definitely should be in your distro’s repositories.

Tip
 If you’re new to git and want to learn more, I highly recommend the book Pro Git. It is available for free download (or online reading).

You can clone via https:

git clone https://git.square-r00t.net/BDisk

or native git protocol:

git clone git://git.square-r00t.net/bdisk.git BDisk

The git protocol is much faster, but at a cost of lessened security.

Note
 I also have a mirror at GitHub, but I don’t like GitHub very much and since it’s a mirror repository, it’s possible it will be out of date. For this reason, it’s recommended that you use the resources above.

Prerequisites

This is a list of software you’ll need available to build with BDisk.

Tip
 Your distro’s package manager should have most if not all of these available, so it’s unlikely you’ll need to install from source.
Note
 Some versions may be higher than actually needed (especially gcc).
Caution
 You will need at least about 15GB of free disk space, depending on what options you enable. Each architecture chroot (i.e. x86_64, i686) is about 3.5GB after a build using the default package set (more on that later), each architecture release tarball (what we use to build the chroots) is approximately 115MB each, and each squashed image per architecture is 1.1GB (if you use the default package set). If you don’t understand what this means quite yet, don’t worry- we’ll go into more detail later on. Just know that you’ll need a fair bit of free disk space.

Build Environment

  • GNU/Linux (relatively recent release of preferred distro)

    • Building on FreeBSD and other *BSDs may be possible via the use of jails. This is entirely untested and no support nor testing will be offered by the author (me). If you would like to offer documentation for this, please contact me.

    • Building on Windows may be possible via the use of the WSL (Windows Subsystem for Linux). This is entirely untested and no support nor testing will be offered by the author (me). If you would like to offer documentation for this, please contact me.

    • Building on macOS is simply not supported, period, due to chroots being necessary to the build functionality of BDisk (and macOS not being able to implement GNU/Linux chroots). You’ll need to run a build VM.

  • Python (>=3.6)

Necessary

These are needed for using BDisk.

These are required Python modules:

Optional

While not strictly necessary, these will greatly enhance your BDisk usage. I’ve included some reasons why you might want to install them.

Note
 If you do not wish to install any of these or cannot install them, be sure to disable the relevant options in the build.ini file (we’ll talk about that later). The default extra/dist.build.ini should be sane enough to not require any of these.

  • gcc (multilib) (>=6.x)

    • Needed for building iPXE.

  • gcc-libs (multilib) (>=6.x)

    • (Same as gcc.)

  • git

    • For autodetection of version, automatically making commits for your project, checking out source code, etc.

  • gpg/gnupg (>=2.1.11)

    • For automatically signing releases, verifying downloaded files from the Internet as part of the build process, etc. It’s okay if you don’t have a key set up!

  • rsync

    • For syncing built ISOs to a fileserver, syncing to a remote iPXE server, syncing to a traditional PXE/TFTP server, etc.

These are optional Python modules:

  • GitPython

    • (Same reasons as git)

  • PyGPGME

    • (Same reasons as gpg/gnupg)

  • Patch

    • For branding iPXE environments per your build.ini.

  • PyOpenSSL

    • To set up a PKI when building iPXE; used to create trusted/verified images.