Metadata-Version: 2.1
Name: fchroot
Version: 0.1
Summary: Funtoo franken-chroot tool.
Home-page: https://code.funtoo.org/bitbucket/users/drobbins/repos/fchroot/browse
Author: Daniel Robbins
Author-email: drobbins@funtoo.org
License: UNKNOWN
Description: # fchroot
        
        ## Introduction
        
        `fchroot`, also known as "Franken-Chroot" or "Funtoo Chroot", is a utility that helps
        you to leverage the magic of QEMU to chroot into a non-native system. For example,
        on your x86-compatible 64-bit PC, it is possible to chroot into a 32-bit or 64-bit
        ARM environment and have it actually work. 
        
        This is accomplished by leveraging the
        "binfmt-misc" functionality built-in to the Linux kernel, combined with QEMU to
        perform emulation of non-native instruction sets. `fchroot` itself doesn't do any
        magic except provide a very easy-to-use mechanism to get this to work, typically
        requiring little or no manual configuration. You simply run `fchroot` just like
        `chroot`, and everything works. Well, I suppose that is a bit magical :) Here's an
        example of how things work with fchroot. Let's say you are on your 64-bit x86-64
        PC, and want to enter a 64-bit ARM environment. Do this:
        
        ```bash
        my64bitpc # tar xpvf stage3-arm64bit.tar.xz
        my64bitpc # fchroot arm64-root
        >>> arm-64bit frankenchroot B]...
        #
        ```
        
        That last `#` prompt may not look like anything special, but you are now inside a
        64-bit ARM frankenchroot. A 64-bit ARM shell is providing that prompt to you, and
        if you run a standard Linux command, it will be running the 64-bit ARM variant of
        that command using QEMU emulation. Pretty cool stuff.
        
        ## What `fchroot` Does For You
        
        The `fchroot` command does lots of things automatically for you to make your 
        franken-chroot experience as seamless as possible. First, note that `fchroot` is
        designed to have a similar calling convention to the standard Linux `chroot` command --
        in fact, at the very end of doing all its magic, it passes all of its arguments to
        `chroot` to get you inside the frankenchroot. But `fchroot` does quite a bit of
        grunt-work to make the `chroot` work:
        
        * `fchroot` will look inside the specified directory and attempt to auto-detect
        what kind of non-native environment it's dealing with. It will currently recognize arm-32bit
        and arm-64bit environments.
        * `fchroot` will check to see if QEMU is available for the detected non-native
        architecture and abort with a (hopefully) useful error message if it is not.
        * `fchroot` will use `gcc` to compile a special wrapper that will be used inside
        the chrooted environment, and store it in `/usr/share/fchroot/wrappers` so it is
        available for later use.
        * `fchroot` will leverage Linux's `binfmt_misc` functionality and register a handler
        so that the kernel will know to use our wrapper (and QEMU) to run non-native binaries.
        * `fchroot` will copy the necessary QEMU binary as well as its wrapper into 
        `/usr/local/bin/` inside the chrooted environment.
        * `fchroot` will mount `/proc`, `/dev` (bind-mount) and `/sys` (bind-mount) within the
        chroot environment automatically if they are not already mounted.
        * `fchroot` will copy the local system's `/etc/resolv.conf` to the chroot environment
        so that DNS resolution will work properly.
        * `fchroot` will then `execvp` the `chroot` command to place you inside the franken-chroot
        environment.
        
        ## Prerequisites
        
        This section lists the prerequisites for getting `fchroot` running -- in other words,
        the things that *you* are responsible for ensuring are done. `fchroot` takes care
        of the rest.
        
        ### Host and Emulated System
        
        ``fchroot`` has been used on x86-compatible 64-bit systems, and currently supports
        arm-32bit and arm-64bit chrooted environments. It is relatively easy to add support
        for new native and emulated systems -- the code is designed to accept patches for
        new architectures -- but for now, be aware of the current architectures supported.
        
        ### QEMU
        
        QEMU will need to be installed with the ``aarch64`` and ``arm`` user targets enabled.
        In addition, it will need to be compiled as a *static* binary. In Funtoo Linux and
        Gentoo Linux, this can be accomplished by adding the following configuration
        prior to running ``emerge qemu``:
        
        Add to ``/etc/make.conf``:
        
        ```bash
        QEMU_USER_TARGETS="aarch64 arm"
        ```
        
        Add to ``/etc/portage/package.use``:
        
        ```bash
        app-emulation/qemu static-user
        dev-libs/glib static-libs
        sys-apps/attr static-libs
        sys-libs/zlib static-libs
        dev-libs/libpcre static-libs
        ```
        
        ### binfmt_misc
        
        In addition, you will need to ensure that ``binfmt_misc`` functionality is enabled
        in-kernel or as a module. By default, this is the case when using Funtoo Linux with
        its default ``debian-sources-lts`` kernel.
        
        ## Setup
        
        The easiest way to set up `fchroot` is to clone it directly from https://code.funtoo.org:
        
        ```bash
        # git clone https://code.funtoo.org/bitbucket/scm/~drobbins/fchroot.git
        ```
        
        You can then simply run ``fchroot`` directly from the git repository:
        
        ```bash
        # fchroot/bin/fchroot /path/to/chroot
        ```
        
        ## Acknowledgements
        
        The `fchroot` command automates a process that was documented at the following locations:
        
        * https://wiki.gentoo.org/wiki/Embedded_Handbook/General/Compiling_with_qemu_user_chroot
        * https://github.com/sakaki-/gentoo-on-rpi3-64bit/wiki/Build-aarch64-Packages-on-your-PC%2C-with-User-Mode-QEMU-and-binfmt_misc
        
        Many thanks to Sakaki and others who documented this process.
        
        ## Contributing
        
        To contribute, please visit https://code.funtoo.org/bitbucket/users/drobbins/repos/fchroot/browse and submit a pull request.
        For more information on how to submit pull requests on code.funtoo.org, see the following YouTube video: https://www.youtube.com/watch?v=V6PfB64oMWo
        
        ## Author and Copyright
        
        This software is written by Daniel Robbins <drobbins@funtoo.org> and is distributed 
        under the GNU General Public License version 2, or later.
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.7
Description-Content-Type: text/markdown
