bdisk/docs/manual/user/GETTING_STARTED.adoc

5.5 KiB
Raw Blame History

Getting Started

Downloading

If it isnt in your distros repositories (It is in Archs AUR! Both tagged release and git master.), you can still easily get rolling. Simply visit the projects 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 distros repositories.

Tip
If youre 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 dont like GitHub very much and since its a mirror repository, its possible it will be out of date. For this reason, its recommended that you use the resources above.

Prerequisites

This is a list of software youll need available to build with BDisk.

Tip
Your distros package manager should have most if not all of these available, so its unlikely youll 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 dont understand what this means quite yet, dont worry- well go into more detail later on. Just know that youll 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). Youll 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. Ive 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 (well 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. Its okay if you dont 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.