From 99561565aa4726d20c5490a2140a6abd2db9c5d4 Mon Sep 17 00:00:00 2001 From: r00t Date: Sat, 17 Dec 2016 17:22:38 -0500 Subject: [PATCH] working on some docs --- docs/manual/BODY.adoc | 3 +- docs/manual/FAQ.adoc | 9 +++++ docs/manual/USER.adoc | 2 +- docs/manual/dev/FUNCTIONS.adoc | 3 ++ docs/manual/faq/INDEX.adoc | 1 + docs/manual/faq/WHYARCH.adoc | 5 +++ docs/manual/user/GETTING_STARTED.adoc | 47 +++++++++++++++++++++++- docs/manual/user/IMPORTANT_CONCEPTS.adoc | 10 +++++ 8 files changed, 77 insertions(+), 3 deletions(-) create mode 100644 docs/manual/FAQ.adoc create mode 100644 docs/manual/faq/INDEX.adoc create mode 100644 docs/manual/faq/WHYARCH.adoc create mode 100644 docs/manual/user/IMPORTANT_CONCEPTS.adoc diff --git a/docs/manual/BODY.adoc b/docs/manual/BODY.adoc index f147782..97770f3 100644 --- a/docs/manual/BODY.adoc +++ b/docs/manual/BODY.adoc @@ -1,4 +1,5 @@ include::USER.adoc[] include::DEV.adoc[] +include::FAQ.adoc[] -include::FOOT.adoc[] +include::FOOT.adoc[] \ No newline at end of file diff --git a/docs/manual/FAQ.adoc b/docs/manual/FAQ.adoc new file mode 100644 index 0000000..154421d --- /dev/null +++ b/docs/manual/FAQ.adoc @@ -0,0 +1,9 @@ += 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! +-- + +include::faq/INDEX.adoc[] diff --git a/docs/manual/USER.adoc b/docs/manual/USER.adoc index 8851918..5e55d23 100644 --- a/docs/manual/USER.adoc +++ b/docs/manual/USER.adoc @@ -18,6 +18,6 @@ This manual will give you the information you need to build your very own live G -- include::user/GETTING_STARTED.adoc[] - +include::user/IMPORTANT_CONCEPTS.adoc[] include::user/PROJECT_LAYOUT.adoc[] diff --git a/docs/manual/dev/FUNCTIONS.adoc b/docs/manual/dev/FUNCTIONS.adoc index fae6cb6..2dbc410 100644 --- a/docs/manual/dev/FUNCTIONS.adoc +++ b/docs/manual/dev/FUNCTIONS.adoc @@ -3,3 +3,6 @@ text == Moar Functions and more text. + + + diff --git a/docs/manual/faq/INDEX.adoc b/docs/manual/faq/INDEX.adoc new file mode 100644 index 0000000..6124f52 --- /dev/null +++ b/docs/manual/faq/INDEX.adoc @@ -0,0 +1 @@ +include::WHYARCH.adoc[] diff --git a/docs/manual/faq/WHYARCH.adoc b/docs/manual/faq/WHYARCH.adoc new file mode 100644 index 0000000..02eb81d --- /dev/null +++ b/docs/manual/faq/WHYARCH.adoc @@ -0,0 +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. + +Plus they have tarballs all ready for chroot easily accessible. + diff --git a/docs/manual/user/GETTING_STARTED.adoc b/docs/manual/user/GETTING_STARTED.adoc index 5b90a5e..12e7f2e 100644 --- a/docs/manual/user/GETTING_STARTED.adoc +++ b/docs/manual/user/GETTING_STARTED.adoc @@ -32,5 +32,50 @@ or native git protocol: The git protocol is much faster, but at a cost of lessened security. === Prerequisites -Here's a complete list of 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. + +==== 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) + +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] + +==== 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). + +* 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) +** 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. \ No newline at end of file diff --git a/docs/manual/user/IMPORTANT_CONCEPTS.adoc b/docs/manual/user/IMPORTANT_CONCEPTS.adoc new file mode 100644 index 0000000..642f4a5 --- /dev/null +++ b/docs/manual/user/IMPORTANT_CONCEPTS.adoc @@ -0,0 +1,10 @@ +== Important Concepts +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. + +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. \ No newline at end of file