bdisk/docs/manual/user/GETTING_STARTED.adoc

== Getting Started

=== Downloading
If it isn't in your distro's repositories (It *is* in Arch's AUR! Both https://aur.archlinux.org/packages/bdisk/[tagged release^] and https://aur.archlinux.org/packages/bdisk-git/[git master^].), you can still easily get rolling. Simply visit the project's https://git.square-r00t.net/BDisk/[source code web interface^] and download a tarball under the *Download* column:

image::fig1.1.png[cgit,align="center"]

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 https://git-scm.com/[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 https://git-scm.com/book/en/v2[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 https://github.com/johnnybubonic/BDisk[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 https://www.freebsd.org/doc/handbook/jails.html[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_the_author,contact me>>.
** Building on Windows *may* be possible via the use of the https://docs.microsoft.com/en-us/windows/wsl/install-win10[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_the_author,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.
* https://www.python.org/[Python^] (>=3.6)

==== Necessary
These are needed for using BDisk.

* https://github.com/dosfstools/dosfstools[dosfstools^]
* http://libburnia-project.org[libisoburn^]
* http://squashfs.sourceforge.net[squashfs-tools^] (>=4.2)

These are required Python modules:
// TODO: double-check/update these.

* https://pypi.python.org/pypi/humanize[Humanize^]
* http://jinja.pocoo.org/[Jinja2^]
* https://pypi.python.org/pypi/psutil[PSUtil^]
* https://pypi.python.org/pypi/validators[Validators^]

==== 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.

* http://gcc.gnu.org[gcc (multilib)^] (>=6.x)
** Needed for building iPXE.
* http://gcc.gnu.org[gcc-libs (multilib)^] (>=6.x)
** (Same as _gcc_.)
* https://git-scm.com/[git^]
** For autodetection of version, automatically making commits for your project, checking out source code, etc.
* https://www.gnupg.org/[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!
* https://rsync.samba.org/[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:

* https://pypi.python.org/pypi/GitPython[GitPython^]
** (Same reasons as _git_)
* https://pypi.python.org/pypi/pygpgme[PyGPGME^]
** (Same reasons as _gpg/gnupg_)
* https://pypi.python.org/pypi/patch[Patch^]
** For branding iPXE environments per your `build.ini`.
* https://pypi.python.org/pypi/pyOpenSSL[PyOpenSSL^]
** To set up a PKI when building iPXE; used to create trusted/verified images.