r00t2/bdisk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Activity

updating documentation...

Browse Source
This commit is contained in:
brent s.
2016-12-19 08:44:19 -05:00
parent 2187d7ac55
commit 9887ee005e
16 changed files with 124 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/manual/user/GETTING_STARTED.adoc
View File

@@ -1,7 +1,7 @@
== 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:
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"]
@@ -15,9 +15,9 @@ or wget:
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.
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).
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:
@@ -29,6 +29,8 @@ or native git protocol:
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.
@@ -41,40 +43,40 @@ CAUTION: You will need at least about *15GB* of free disk space, depending on wh
==== Necessary
These are needed for using BDisk.
* https://www.python.org/[Python] (>=3.5)
* https://github.com/dosfstools/dosfstools[dosfstools]
* http://gcc.gnu.org[gcc (multilib)] (>=6.x)
* http://gcc.gnu.org[gcc-libs (multilib)] (>=6.x)
* http://libburnia-project.org[libisoburn]
* http://squashfs.sourceforge.net[squashfs-tools] (>=4.2)
* https://www.python.org/[Python^] (>=3.5)
* https://github.com/dosfstools/dosfstools[dosfstools^]
* http://gcc.gnu.org[gcc (multilib)^] (>=6.x)
* http://gcc.gnu.org[gcc-libs (multilib)^] (>=6.x)
* http://libburnia-project.org[libisoburn^]
* http://squashfs.sourceforge.net[squashfs-tools^] (>=4.2)
These are required Python modules:
* 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]
* 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.
* https://git-scm.com/[git]
* https://git-scm.com/[git^]
** For autodetection of version, automatically making commits for your project, etc.
* https://www.gnupg.org/[gpg/gnupg] (>=2.1.11)
* 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]
* 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]
* https://pypi.python.org/pypi/GitPython[GitPython^]
** (Same reasons as _git_)
* https://pypi.python.org/pypi/pygpgme[PyGPGME]
* https://pypi.python.org/pypi/pygpgme[PyGPGME^]
** (Same reasons as _gpg/gnupg_)
* https://pypi.python.org/pypi/patch[Patch]
* https://pypi.python.org/pypi/patch[Patch^]
** For branding iPXE environments per your `build.ini`.
* https://pypi.python.org/pypi/pyOpenSSL[PyOpenSSL]
* https://pypi.python.org/pypi/pyOpenSSL[PyOpenSSL^]
** To set up a PKI when building iPXE; used to create trusted/verified images.

36
docs/manual/user/IMPORTANT_CONCEPTS.adoc
View File

@@ -2,15 +2,41 @@
If this is your first foray into building live distros, there are some terms and concepts we need to understand first. This will simplify the process later on.
=== Terms
An *operating system* is what your programs (email client, web browser, etc.) run on.
An *operating system*, or OS, is what your programs (email client, web browser, etc.) run on.
There are two basic types of booting systems that communicate between the *hardware* (the physical computer itself and its components) and the operating system: https://en.wikipedia.org/wiki/BIOS[*BIOS*] (Basic Input/Output System) which has been around for quite some time and the newer https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface[*UEFI*] (Unified Extensible Firmware Interface). Don't worry, you don't need to memorize what they're acronyms for and there won't be an exam -- just remember that BIOS is an older technology and UEFI is the newer one (and that they operate differently).
There are two basic types of booting systems that communicate between the *hardware* (the physical computer itself and its components) and the operating system: https://en.wikipedia.org/wiki/BIOS[*BIOS*^] (Basic Input/Output System) which has been around for quite some time and the newer https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface[*UEFI*^] (Unified Extensible Firmware Interface). Don't worry, you don't need to memorize what they're acronyms for and there won't be an exam -- just remember that BIOS is an older technology and UEFI is the newer one (and that they operate differently).
*GNU/Linux*, sometimes just referred to as _Linux_ (And there is a difference between the terminologies, but it's nuanced. You are welcome to https://www.gnu.org/gnu/linux-and-gnu.en.html[read up on it] though!), is an example of an operating system. Other examples include _Windows_, _macOS_ (previously _OS X_), _iOS_, _Android_, and a whole slew of others.
*GNU/Linux*, sometimes just referred to as _Linux_ (And there is a difference between the terminologies, but it's nuanced. You are welcome to https://www.gnu.org/gnu/linux-and-gnu.en.html[read up on it^] though!), is an example of an operating system. Other examples include _Windows_, _macOS_ (previously _OS X_), _iOS_, _Android_, and a whole slew of others. There are many types of GNU/Linux offerings, called _distributions_, _flavors_, or _distros_.
A *live distro*, *live CD*, *live DVD*, *live USB*, and the like are a way of booting an operating system without installing it on the hard drive- this means the computer doesn't even need a hard drive installed, or it doesn't matter if the installed operating system is broken. Typically they are Linux-based, but there are several Windows-based live releases out there (usually they're focused on rescuing broken Windows systems, so they're not very flexible).
=== Why live media is necessary
*Hybrid ISOs* are ISO files that can be burned to optical media (CDs, DVDs, etc.) and also be _dd_'d directly to a USB thumbdrive (for computers that support booting from USB). That means one file, multiple media types.
*Architectures* are different hardware platforms. This mostly refers to the CPU. Common implementations are *64-bit* (also known as *x86_64* or *AMD64* for ones that support running both 64-bit and 32-bit software, or *IA64* or *Itanium* for processors that only support 64-bit) and *32-bit* (or *i686* and the older *i386* and *i486* implementations). Most consumer PCs on the market today are x86_64.
*Chroots*, *chrooting*, and the like are variants on the word *chroot*. A *chroot* is a way of running a GNU/Linux install "inside" another GNU/Linux distro. It's sort of like a virtual machine, or VM, except that it's a lot more lightweight and it doesn't do any actual virtualization- and uses the host's kernel, memory mapping, etc. It's very useful for development of operating systems.
=== Why live media is necessary/Why you might want BDisk
"But Brent," I hear you ask in a voice which most likely is nothing close to what you actually sound like and entirely in my head, "Why would I need a live CD/USB/etc.? And why BDisk?"
Elementary, my dear imaginary reader! I touch on some reasons why one might want live media in the beginning of the User Manual, but
Elementary, my dear imaginary reader! I touch on some reasons why one might want live media in the beginning of the <<USER.adoc#_user_manual,User Manual>>, but here's why you might want BDisk specifically as opposed to another live distro (or <<FAQ.adoc#_i_don_t_like_bdisk_are_there_any_other_alternatives,live distro creator>>).
* Fully customizable
* Works with a multitude of GNU/Linux distros -- both for the host build system and as the guest. (Still under development!)
* It performs optimizations and compression to help you get the smallest ISO possible.
* In addition to building hybrid ISOs, it supports building iPXE hybrid ISOs (meaning you only need a very small file; the rest of the operating system boots over the Internet).
* It supports both BIOS and UEFI systems- both the full image and the iPXE images.
* It supports multiple architectures (x86_64, i686, possibly IA64 -- untested).
* It supports automatically syncing to a web mirror, PXE boot server, etc. via rsync upon successful build.
* It supports SecureBoot.
=== Who might want to use BDisk?
* System builders/hardware testers
* System Administrators/Engineers/Architects
* Information Security professionals
* Computer repair shops
* Technology Consultants
* Hobbyists
* Home GNU/Linux users
* Technology enthusiasts

4
docs/manual/user/PROJECT_LAYOUT.adoc
View File

@@ -1,2 +1,4 @@
== Project Structure
file tree, explain dirs and files
include::fslayout/BDISK.adoc[]

6
docs/manual/user/fslayout/BDISK.adoc Normal file
View File

@@ -0,0 +1,6 @@
== bdisk/
This directory contains the "heart" of BDisk. It essentially is a Python module package. It contains several python "subpackages" split into different files that provide different functions for BDisk.
=== bchroot.py
This file controls creation of the chroots -- the directories in which BDisk builds the actual system that is booted into.