diff --git a/docs/manual/BODY.adoc b/docs/manual/BODY.adoc index 318c628..7329eac 100644 --- a/docs/manual/BODY.adoc +++ b/docs/manual/BODY.adoc @@ -1,5 +1,6 @@ include::USER.adoc[] include::DEV.adoc[] include::BOOT.adoc[] +include::FURTHER.adoc[] +include::FAQ.adoc[] include::FOOT.adoc[] -include::FAQ.adoc[] \ No newline at end of file diff --git a/docs/manual/BOOT.adoc b/docs/manual/BOOT.adoc index 756a0af..d9e6594 100644 --- a/docs/manual/BOOT.adoc +++ b/docs/manual/BOOT.adoc @@ -5,4 +5,4 @@ It's possible to netboot my personal build of BDisk. I mostly keep this up for emergencies in case I need it, but it's good to show you that yes, you can boot a 2GB+ squashed and compressed filesystem from a <50MB image file. -- -include::boot/HOWTO.adoc[] +include::netboot/HOWTO.adoc[] diff --git a/docs/manual/FAQ.adoc b/docs/manual/FAQ.adoc index 7c12101..11a309f 100644 --- a/docs/manual/FAQ.adoc +++ b/docs/manual/FAQ.adoc @@ -1,11 +1,8 @@ = FAQ - [partintro] .What good is software if nobody understands it? -- -Here you will find some answers to Frequently Asked Questions I've received about this project. Please be sure to check this list before opening a bug report or sending a patch! +Here you will find some answers to Frequently Asked Questions I've received about this project. Please be sure to check this list before <> or sending a patch! -- include::faq/INDEX.adoc[] - - diff --git a/docs/manual/FOOT.adoc b/docs/manual/FOOT.adoc index 4a39877..276d7ef 100644 --- a/docs/manual/FOOT.adoc +++ b/docs/manual/FOOT.adoc @@ -2,3 +2,7 @@ = User Manual [appendix] = Developer Manual +[appendix] += Netboot +[appendix] += Bug Reports/Feature Requests \ No newline at end of file diff --git a/docs/manual/FURTHER.adoc b/docs/manual/FURTHER.adoc new file mode 100644 index 0000000..bd16017 --- /dev/null +++ b/docs/manual/FURTHER.adoc @@ -0,0 +1,10 @@ += Further Reading/Resources +[partintro] +.What good is software if you can't interact? +-- +Here you will find further info, other resources, and such relating to BDisk. +-- + +include::further/BUGS.adoc[] +include::further/CONTACT.adoc[] + diff --git a/docs/manual/HEAD.adoc b/docs/manual/HEAD.adoc index 450b2d9..6e95e55 100644 --- a/docs/manual/HEAD.adoc +++ b/docs/manual/HEAD.adoc @@ -34,11 +34,11 @@ It’s my hope that by releasing this utility (and documenting it), you can use === Copyright/Licensing -The BDisk code is https://www.gnu.org/licenses/gpl-3.0.en.html[GPLv3-licensed]. This means that you can use it for business reasons, personal reasons, modify it, etc. Please be sure to familiarize yourself with the full set of terms. You can find the full license in `docs/LICENSE`. +The BDisk code is https://www.gnu.org/licenses/gpl-3.0.en.html[GPLv3-licensed^]. This means that you can use it for business reasons, personal reasons, modify it, etc. Please be sure to familiarize yourself with the full set of terms. You can find the full license in `docs/LICENSE`. image::https://www.gnu.org/graphics/gplv3-127x51.png[GPLv3,align="center"] -This document, and all other associated author-generated documentation, are released under the http://creativecommons.org/licenses/by-sa/4.0/[Creative Commons CC-BY-SA 4.0] copyright. It's essentially the GPL for non-software, so similar terms apply. +This document, and all other associated author-generated documentation, are released under the http://creativecommons.org/licenses/by-sa/4.0/[Creative Commons CC-BY-SA 4.0^] copyright. It's essentially the GPL for non-software, so similar terms apply. image::https://i.creativecommons.org/l/by-sa/4.0/88x31.png[CC-BY-SA_4.0,align="center"] diff --git a/docs/manual/USER.adoc b/docs/manual/USER.adoc index 5e55d23..872af23 100644 --- a/docs/manual/USER.adoc +++ b/docs/manual/USER.adoc @@ -7,10 +7,10 @@ BDisk was ultimately designed to make your life easier. "Why would I possibly ne Using BDisk, you can: -* Install GNU/Linux (https://wiki.archlinux.org/index.php/installation_guide[Arch], https://watchmysys.com/blog/2015/02/installing-centos-7-with-a-chroot/[CentOS], https://www.debian.org/releases/stable/amd64/apds03.html.en[Debian], https://wiki.gentoo.org/wiki/Handbook:AMD64#Installing_Gentoo[Gentoo], https://help.ubuntu.com/lts/installation-guide/powerpc/apds04.html[Ubuntu]...). BDisk may be Arch-based, but many if not most other distros offer ways to install from any GNU/Linux live distribution. -* Perform disk maintenance (https://raid.wiki.kernel.org/index.php/RAID_setup[mdadm], fdisk/http://www.rodsbooks.com/gdisk/[gdisk], http://gparted.org/[gparted], https://www.thomas-krenn.com/en/wiki/StorCLI[storcli], etc.). Need to replace that disk in your RAID and you don't have hotswap? Not a problem! -* Rescue, recover, wipe (http://www.sleuthkit.org/sleuthkit/[scalpel], http://www.andybev.com/index.php/Nwipe[nwipe], http://foremost.sourceforge.net/[foremost], etc.). Chances are this is why you booted a live distro in the first place, yes? -* Boot over the Internet (or LAN). Burning a new image to CD/DVD/USB is a pain. BDisk has built-in support for http://ipxe.org/[iPXE] (and traditional PXE setups). Update the filesystem image once, deploy it everywhere. +* Install GNU/Linux (https://wiki.archlinux.org/index.php/installation_guide[Arch^], https://watchmysys.com/blog/2015/02/installing-centos-7-with-a-chroot/[CentOS^], https://www.debian.org/releases/stable/amd64/apds03.html.en[Debian^], https://wiki.gentoo.org/wiki/Handbook:AMD64#Installing_Gentoo[Gentoo^], https://help.ubuntu.com/lts/installation-guide/powerpc/apds04.html[Ubuntu^]...). BDisk may be Arch-based, but many if not most other distros offer ways to install from any GNU/Linux live distribution. +* Perform disk maintenance (https://raid.wiki.kernel.org/index.php/RAID_setup[mdadm^], fdisk/http://www.rodsbooks.com/gdisk/[gdisk^], http://gparted.org/[gparted^], https://www.thomas-krenn.com/en/wiki/StorCLI[storcli^], etc.). Need to replace that disk in your RAID and you don't have hotswap? Not a problem! +* Rescue, recover, wipe (http://www.sleuthkit.org/sleuthkit/[scalpel^], http://www.andybev.com/index.php/Nwipe[nwipe^], http://foremost.sourceforge.net/[foremost^], etc.). Chances are this is why you booted a live distro in the first place, yes? +* Boot over the Internet (or LAN). Burning a new image to CD/DVD/USB is a pain. BDisk has built-in support for http://ipxe.org/[iPXE^] (and traditional PXE setups). Update the filesystem image once, deploy it everywhere. * And much, much more. ** Seriously. diff --git a/docs/manual/faq/ALTERNATIVES.adoc b/docs/manual/faq/ALTERNATIVES.adoc index 4dd83ad..e6d9449 100644 --- a/docs/manual/faq/ALTERNATIVES.adoc +++ b/docs/manual/faq/ALTERNATIVES.adoc @@ -1,11 +1,11 @@ == I don't like BDisk. Are there any other alternatives? -First, I'm sorry to hear that BDisk doesn't suit your needs. If you want any features you think are missing or encounter any bugs, please report them! +First, I'm sorry to hear that BDisk doesn't suit your needs. If you want any features you think are missing or encounter any <>, please report them! But yes; there are plenty of alternatives! NOTE: Only *currently maintained projects* are listed here. -=== https://wiki.archlinux.org/index.php/archboot[Archboot] +=== https://wiki.archlinux.org/index.php/archboot[Archboot^] Written in Bash [frame="topbot",options="header,footer"] |====================== @@ -28,7 +28,7 @@ Written in Bash || |====================== -=== https://wiki.archlinux.org/index.php/archiso[Archiso] +=== https://wiki.archlinux.org/index.php/archiso[Archiso^] Written in Bash. [frame="topbot",options="header,footer"] |====================== @@ -45,7 +45,7 @@ Written in Bash. || |====================== -=== Debian's https://wiki.debian.org/Simple-CDD[Simple-CDD] +=== Debian's https://wiki.debian.org/Simple-CDD[Simple-CDD^] Written in Bash. [frame="topbot",options="header,footer"] |====================== @@ -54,7 +54,7 @@ Written in Bash. || |====================== -=== Fedora's https://fedoraproject.org/wiki/Livemedia-creator-_How_to_create_and_use_a_Live_CD[Livemedia-creator] +=== Fedora's https://fedoraproject.org/wiki/Livemedia-creator-_How_to_create_and_use_a_Live_CD[Livemedia-creator^] Written in Bash. [frame="topbot",options="header,footer"] |====================== @@ -63,7 +63,7 @@ Written in Bash. || |====================== -=== https://github.com/rhinstaller/livecd-tools[LiveCD Tools] +=== https://github.com/rhinstaller/livecd-tools[LiveCD Tools^] Written in Bash. [frame="topbot",options="header,footer"] |====================== diff --git a/docs/manual/faq/WHYARCH.adoc b/docs/manual/faq/WHYARCH.adoc index b5f7e7c..2a468c8 100644 --- a/docs/manual/faq/WHYARCH.adoc +++ b/docs/manual/faq/WHYARCH.adoc @@ -1,5 +1,5 @@ == Why Arch Linux? -Because it's a very easy-to-use, simple, https://wiki.archlinux.org/[well-documented] distro. It's no-frills and incredibly flexible/customizable, and can be made rather slim (and is out of the box, in fact). It's also very friendly to run as a chroot inside any other distro or as a chroot host to any other distro. +Because it's a very easy-to-use, simple, https://wiki.archlinux.org/[well-documented^] distro. It's no-frills and incredibly flexible/customizable, and can be made rather slim (and is out of the box, in fact). It's also very friendly to run as a chroot inside any other distro or as a chroot host to any other distro. Plus they release monthly tarball snapshots that are fairly small and create quick bootstrap environments. diff --git a/docs/manual/further/BUGS.adoc b/docs/manual/further/BUGS.adoc new file mode 100644 index 0000000..a69325b --- /dev/null +++ b/docs/manual/further/BUGS.adoc @@ -0,0 +1,16 @@ +== Bug Reports/Feature Requests +=== Bugs +If you encounter any bugs in *BDisk*, you can file a bug report https://bugs.square-r00t.net/index.php?do=newtask&project=2&task_type=1[here^]. + +If you encounter any bugs (inaccurate information, typos, misformatting, etc.) in *this documentation*, you can file a bug report https://bugs.square-r00t.net/index.php?do=newtask&project=8&task_type=1[here^]. + +=== Feature Requests +If you have any features you'd like to see or you think would help *BDisk* become even more useful, please file a feature request https://bugs.square-r00t.net/index.php?do=newtask&project=2&task_type=2[here^]. + +If you have any suggestions on how to improve *this documentation* or feel it's missing information that could be useful, please file a feature request https://bugs.square-r00t.net/index.php?do=newtask&project=8&task_type=2[here^]. + +=== Patches +I gladly welcome patches, but I deplore using GitHub (even though I https://github.com/johnnybubonic/BDisk[have a mirror there^]). For this reason, please follow the same https://www.kernel.org/doc/Documentation/SubmittingPatches[patch/pull request process] for the Linux kernel and email it to bts@square-r00t.net. + +Alternatively, you may attach a patch to a <<_bugs,bug report>>. + diff --git a/docs/manual/further/CONTACT.adoc b/docs/manual/further/CONTACT.adoc new file mode 100644 index 0000000..b68a3f6 --- /dev/null +++ b/docs/manual/further/CONTACT.adoc @@ -0,0 +1,10 @@ +== Contact the Author +If you have any questions, comments, or concerns, you can use the following information to get in touch with me. + +I am available via mailto:bts@square-r00t.net[email]. If you use GPG, you can find my pubkey and other related info https://devblog.square-r00t.net/about/my-gpg-public-key-verification-of-identity[here^] (and on most keyservers). + +I occasionally write howto articles, brief tips, and other information in my https://devblog.square-r00t.net[dev blog]. + +I am on IRC as *r00t^2*, and am usually in the irc://irc.freenode.org/#sysadministrivia[Sysadministrivia channel on Freenode]. Which reminds me, I run a podcast called https://sysadministrivia.com[Sysadministrivia^]. + +I am on Twitter as https://twitter.com/brentsaner[@brentsaner^], though I don't tweet very often. (I usually tweet from my https://twitter.com/SysAdm_Podcast[podcast's twitter^].) diff --git a/docs/manual/boot/HOWTO.adoc b/docs/manual/netboot/HOWTO.adoc similarity index 86% rename from docs/manual/boot/HOWTO.adoc rename to docs/manual/netboot/HOWTO.adoc index 84db791..6414c64 100644 --- a/docs/manual/boot/HOWTO.adoc +++ b/docs/manual/netboot/HOWTO.adoc @@ -3,7 +3,7 @@ I update this server with images and iPXE images you can use to netboot my perso You can https://bdisk.square-r00t.net/download/bdisk-mini.iso[download] a demo of the iPXE functionality. Note that your computer needs to be connected to a valid Internet connection via ethernet and be able to get a DHCP lease for it to work. -NOTE: Advanced users, you can https://www.gnupg.org/gph/en/manual/x135.html[verify] it against the GPG signature (https://bdisk.square-r00t.net/download/bdisk-mini.iso.asc[ASC], https://bdisk.square-r00t.net/download/bdisk-mini.iso.gpg[BIN]). My key can be found in https://square-r00t.net/gpg/ascii/personal.asc[ASC] or https://square-r00t.net/gpg/bin/personal.gpg[BIN] format. Proofs of identity can be found in the footnotes of https://devblog.square-r00t.net/articles/a-note-on-using-gpg-signatures-in-pkgbuilds[this] blog post. Note that while this project is in flux, I may be signing with temporarily-generated throwaway keys. +NOTE: Advanced users, you can https://www.gnupg.org/gph/en/manual/x135.html[verify^] it against the GPG signature (https://bdisk.square-r00t.net/download/bdisk-mini.iso.asc[ASC], https://bdisk.square-r00t.net/download/bdisk-mini.iso.gpg[BIN]). Please see https://devblog.square-r00t.net/about/my-gpg-public-key-verification-of-identity[this blog post^] for information on fetching my keys and such. Note that while this project is in flux, I may be signing with temporarily-generated throwaway keys. Once downloaded, you can follow the appropriate steps based on your operating system: @@ -12,9 +12,9 @@ Once downloaded, you can follow the appropriate steps based on your operating sy Simply put a blank CD/DVD-R (or RW, RW+, etc.) in your optical media drive. Find where you downloaded the above file (it should be named `bdisk-mini.iso`). Right-click and select *Burn disc image*. ==== USB -You'll most likely want to https://svwh.dl.sourceforge.net/project/usbwriter/USBWriter-1.3.zip[download] a program caled https://sourceforge.net/projects/usbwriter/[USBWriter]. Unzip it (or just open it via double-clicking) and copy the `USBWriter.exe` program somewhere you'll remember- your desktop, for instance. +You'll most likely want to https://svwh.dl.sourceforge.net/project/usbwriter/USBWriter-1.3.zip[download] a program called https://sourceforge.net/projects/usbwriter/[USBWriter^]. Unzip it (or just open it via double-clicking) and copy the `USBWriter.exe` program somewhere you'll remember- your desktop, for instance. -Next, make sure your USB thumbdrive is inserted in your computer and https://support.microsoft.com/en-us/help/17418/windows-7-create-format-hard-disk-partition[formatted/"initialized"] already. +Next, make sure your USB thumbdrive is inserted in your computer and https://support.microsoft.com/en-us/help/17418/windows-7-create-format-hard-disk-partition[formatted/"initialized"^] already. WARNING: Formatting a disk/partition will *destroy* any and all data on that device! Make sure there is nothing on your USB drive you want to keep, as formatting BDisk to it *will* delete any data on it. @@ -83,7 +83,7 @@ Strangely enough, you should still be able to _boot_ a BDisk Mini CD/DVD, you ju === GNU/Linux ==== CD/DVD -Easy. Most (if not all) of https://wiki.archlinux.org/index.php/Optical_disc_drive#Burning[these] should support burning `bdisk-mini.iso` to disc (I'm partial to _cdrecord_). If you prefer a GUI, try some of https://wiki.archlinux.org/index.php/Optical_disc_drive#Burning_CD.2FDVD.2FBD_with_a_GUI[these] instead (I like _k3b_). +Easy. Most (if not all) of https://wiki.archlinux.org/index.php/Optical_disc_drive#Burning[these^] should support burning `bdisk-mini.iso` to disc (I'm partial to _cdrecord_). If you prefer a GUI, try some of https://wiki.archlinux.org/index.php/Optical_disc_drive#Burning_CD.2FDVD.2FBD_with_a_GUI[these^] instead (I like _k3b_). ==== USB Very similar to OS X/macOS in approach. First open a terminal emulator- the ways of navigating to it depends on your window manager/desktop environment, but it's usually under a System or Utilities menu. @@ -125,3 +125,4 @@ If you get a popup from your desktop environment (assuming you're using one) abo ==== Booting Exactly the same as those for Windows. (Unless you're running GNU/Linux on Mac hardware, in which case follow the booting instructions for Mac instead.) + diff --git a/docs/manual/user/GETTING_STARTED.adoc b/docs/manual/user/GETTING_STARTED.adoc index f93114d..e9186ed 100644 --- a/docs/manual/user/GETTING_STARTED.adoc +++ b/docs/manual/user/GETTING_STARTED.adoc @@ -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. diff --git a/docs/manual/user/IMPORTANT_CONCEPTS.adoc b/docs/manual/user/IMPORTANT_CONCEPTS.adoc index 6a74530..3be4c2b 100644 --- a/docs/manual/user/IMPORTANT_CONCEPTS.adoc +++ b/docs/manual/user/IMPORTANT_CONCEPTS.adoc @@ -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 \ No newline at end of file +Elementary, my dear imaginary reader! I touch on some reasons why one might want live media in the beginning of the <>, but here's why you might want BDisk specifically as opposed to another live distro (or <>). + +* 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 + diff --git a/docs/manual/user/PROJECT_LAYOUT.adoc b/docs/manual/user/PROJECT_LAYOUT.adoc index 5806240..4132857 100644 --- a/docs/manual/user/PROJECT_LAYOUT.adoc +++ b/docs/manual/user/PROJECT_LAYOUT.adoc @@ -1,2 +1,4 @@ == Project Structure -file tree, explain dirs and files + +include::fslayout/BDISK.adoc[] + diff --git a/docs/manual/user/fslayout/BDISK.adoc b/docs/manual/user/fslayout/BDISK.adoc new file mode 100644 index 0000000..c4b7ba1 --- /dev/null +++ b/docs/manual/user/fslayout/BDISK.adoc @@ -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. +