Re: [Xen-devel] [PATCH] Add INSTALL file

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 17/10/14 15:50, Olaf Hering wrote:
> Document how to use configure and what to pass to make(1).
>
> Signed-off-by: Olaf Hering <olaf@xxxxxxxxx>

Fantastic document.

Is it possible to put a canonical list of build dependences in here?

> ---
>
> Just to get it out of the door, finally...
>
>  INSTALL | 287 
> ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  README  |   3 +-
>  2 files changed, 288 insertions(+), 2 deletions(-)
>
> diff --git a/INSTALL b/INSTALL
> new file mode 100644
> index 0000000..99c1383
> --- /dev/null
> +++ b/INSTALL
> @@ -0,0 +1,287 @@
> +
> +Compiling Xen from source
> +
> +* Overview
> +* Options recognized by configure
> +* Variables recognized by make
> +* History of options
> +* Examples
> +
> +Overview
> +========
> +
> +The xen source contains four subsystems: xen, tools, stubdom and docs.
> +All but xen has to be prepared for build with a configure script in the

"All but xen have to be"

> +toplevel directory. configure recognizes certain arguments and
> +environment variables which is used to adjust various aspects of the

"variables which are used"

> +following compile process. Once configure is done, make(1) has to be
> +called. Also make recognizes certain arguments. The following sections
> +will give an overview.
> +
> +Options recognized by configure
> +===============================
> +
> +The configure script in the toplevel directory will recognize these
> +options. It will pass them to the configure scripts in the tools,
> +stubdomw and docs directory.
> +
> +Individual subsystems can be selected by one of the following options.
> +Please note that stubdom requires tools. 
> +  --disable-xen
> +  --disable-tools
> +  --enable-stubdom
> +  --disable-docs
> +
> +The well known GNU configure options to specify the target directories.
> +Note: prefix defaults to /usr/local, sysconfdir defaults to /etc,
> +localstatedir defaults to /var.
> +  --prefix=DIR
> +  --libdir=DIR
> +  --libexecdir=BASEDIR
> +  --bindir=DIR
> +  --sbindir=DIR
> +  --sysconfdir=DIR
> +  --sharedstatedir=DIR
> +  --localstatedir=DIR
> +  --includedir=DIR
> +  --datarootdir=DIR
> +  --datadir=DIR
> +  --mandir=DIR
> +  --docdir=DIR
> +
> +To automatically run the toolstack in dom0 during system startup some
> +sysv runlevel scripts are installed. This option allows to set the path
> +for a given system. Possible values are /etc/init.d, /etc/rc.d/init.d or
> +/etc/rc.d. If not specified configure tries to guess the path.
> +  --with-initddir=DIR
> +
> +The runlevel scripts load certain configuration files. They are
> +typically located in a subdirectory of /etc. Possible values are this
> +subdirectory are "sysconfig" or "default". If not specified configure
> +tries to guess the subdir.
> +  --with-sysconfig-leaf-dir=SUBDIR
> +
> +If the tools are configured with a non-standard --prefix the runtime
> +linker will either not find the required libraries or it will load them
> +from a wrong location. Compiling the tools with rpath will force the
> +linker to look in the correct location.
> +  --enable-rpath
> +
> +During build in a git checkout the buildsystem needs to download
> +additional tools such as qemu. This is done with either the native git
> +protocol, or via http if this option is enabled.
> +  --enable-githttp
> +
> +Disable xenstat and xentop monitoring tools.
> +  --disable-monitors
> +
> +Disable build of certain ocaml libaries and tools. To actually build
> +them ocaml development packages must be installed. If they are missing
> +configure will automatically disable this option.
> +  --disable-ocamltools
> +
> +Disable XSM policy compilation.
> +  --disable-xsmpolicy
> +
> +Attempt to build of an OVMF firmware binary. This requires special
> +versions of development tools. Use at your own risk.
> +  --enable-ovmf
> +
> +Use the given OVMF binary instead of compiling a private copy.
> +  --with-system-ovmf=PATH
> +
> +Build a private copy of SeaBIOS.
> +  --disable-seabios
> +
> +Use the given SeaBIOS binary instead of compiling a private copy.
> +  --with-system-seabios=PATH
> +
> +Build the old qemu used by xm/xend. This is required if existing domUs
> +should be migrated to this host, or if existing domU snapshots should be
> +started with this version of the tools. Only if all domUs used the new
> +upstream qemu during initial start it is safe to disable this option.
> +The old qemu requires rombios, wich can be disable along with
> +qemu-traditional.
> +  --enable-qemu-traditional
> +  --enable-rombios
> +
> +The libxl toolstack uses the upstream qemu per default. A private copy
> +will be built. If desired this private copy can be configured with
> +additional options passed to its configure script.
> +  --with-extra-qemuu-configure-args="arg1 arg2"
> +
> +Use the given qemu binary instead of compiling a private copy.
> +  --with-system-qemu=PATH
> +
> +A dom0 requires a set of backend drivers. The configure script already
> +supplies a list of known drivers which are automatically loaded in dom0.
> +This internal list can be changed with this option.
> +  --with-linux-backend-modules="kmod1 kmod2"
> +
> +Two variants of a xenstored exist: the original xenstored written in C
> +(xenstored) or the newer and robust one written in Ocaml (oxenstored).
> +The oxenstored daemon is the default but can only be used if the
> +required ocaml packages are installed. In case they are missing the
> +original xenstored will be used. Valid names are xenstored and
> +oxenstored.
> +  --with-xenstored=name
> +
> +Using additional CFLAGS to build tools running in dom0 is required when
> +building distro packages. This is the option to pass things like
> +RPM_OPT_FLAGS.
> +  --with-extra-cflags-tools=EXTRA_CFLAGS
> +  --with-extra-cflags-qemu-traditional=EXTRA_CFLAGS
> +  --with-extra-cflags-qemu-upstream=EXTRA_CFLAGS
> +
> +Instead of starting the tools in dom0 with sysv runlevel scripts they
> +can also be started by systemd. If this option is enabled xenstored will
> +receive the communication socked directly from systemd. So starting it
> +manually will not work anymore. The paths to systemd internals can also
> +be changed in case the default paths do not fit anymore.
> +NOTE: if systemd development packages are installed the systemd support
> +will be the enabled per default. Using --disable-systemd will override
> +this detection and the sysv runlevel scripts have to be used.
> +  --enable-systemd
> +  --with-systemd=DIR
> +  --with-systemd-modules-load=DIR
> +
> +The old backend drivers are disabled because qdisk is now the default.
> +This option can be used to build them anyway.
> +  --enable-blktap1
> +  --enable-blktap2
> +  
> +Build various stubom components, some are only example code. Its usually
> +enough to specify just --enable-stubdom and leave these options alone.
> +  --enable-ioemu-stubdom
> +  --enable-c-stubdom
> +  --enable-caml-stubdom
> +  --disable-pv-grub
> +  --disable-xenstore-stubdom
> +  --enable-vtpm-stubdom
> +  --enable-vtpmmgr-stubdom
> +  --disable-extfiles
> +
> +Per default some parts of the tools code will print additional runtime
> +debug. This option can be used to disable such code paths.
> +  --disable-debug
> +
> +Variables recognized by make
> +==========================

What about some reference to .config in the top level?  It is what I use
for providing most of these parameters in a XenServer build.

~Andrew

> +
> +The following variables are recognized by the build system. They have to
> +be passed as make options, like 'make variable=value'. Having these
> +variables in the environment, like 'env variable=value make', will not
> +work for most of them.
> +
> +The well known variable to specify an offset during make install,
> +useful for packaing.
> +DESTDIR=
> +
> +Per default some parts of the tools code will print additional runtime
> +debug. This option can be used to disable such code paths. 
> +debug=y
> +debug_symbols=y
> +
> +If --prefix= was used during configure the and ocaml was enabled the
> +resuling libraries will not be installed in the specified path. Instead
> +the path provided by ocamlfind(1) will be used. This variable can be
> +used to override this path. Using the environment variable
> +OCAMLFIND_DESTDIR= and OCAMLFIND_METADIR= will have the same effect.
> +OCAMLDESTDIR=
> +
> +The xen subsystem will install the hypervisor into fixed locations.
> +BOOT_DIR defaults to /boot, EFI_DIR to /usr/lib64/efi.
> +BOOT_DIR=
> +EFI_DIR=
> +
> +The make target 'rpmball' will build a xen.rpm. This variable can be
> +used to append a custom string to the name.
> +PKG_SUFFIX=
> +
> +The hypervisor will report a certain version string. This variable can
> +be used to append a custom string to the version.
> +XEN_VENDORVERSION=
> +
> +During boot xen will report a certain user@host string, which can be
> +changed with these variables.
> +XEN_WHOAMI=
> +XEN_DOMAIN=
> +
> +The following variables can be used to tweak some aspects of the
> +hypervisor build.
> +verbose=y
> +perfc=y
> +perfc_arrays=y
> +lock_profile=y
> +crash_debug=y
> +frame_pointer=y
> +lto=y
> +
> +During tools build external repos will be cloned into the source tree.
> +This variable can be used to point to a different git binary to be used.
> +GIT=
> +
> +During tools build external repos will be cloned into the source tree.
> +During stubdom build external packages will be downloaded into the
> +source tree. These variables can be used to point to a different
> +locations.
> +XEN_EXTFILES_URL=
> +OVMF_UPSTREAM_URL=
> +QEMU_UPSTREAM_URL=
> +QEMU_TRADITIONAL_URL=
> +SEABIOS_UPSTREAM_URL=
> +
> +This variable can be used to use DIR/include and DIR/lib during build.
> +This is the same as PREPEND_LIB and PREPEND_INCLUDES. APPEND_LIB and
> +APPEND_INCLUDES= will be appendend to the CFLAGS/LDFLAGS variable.
> +EXTRA_PREFIX=DIR
> +PREPEND_LIB=DIR
> +PREPEND_INCLUDES=DIR
> +APPEND_LIB=DIR
> +APPEND_INCLUDES=DIR
> +
> +While the tools build will set the path to the python binary with the
> +configure script, the hypervisor build has to use this variable to use a
> +different python binary.
> +PYTHON=
> +
> +Building the python tools may fail unless certain options are passed to
> +setup.py. Config.mk contains additional info how to use this variable.
> +PYTHON_PREFIX_ARG=
> +
> +The hypervisor may be build with XSM support, which can be changed with
> +the following variables.
> +XSM_ENABLE=y
> +FLASK_ENABLE=y
> +
> +Do a build to for coverage.
> +coverage=y
> +
> +Use clang instead of GCC.
> +clang=y
> +
> +
> +History of options
> +==================
> +
> +Prior to xen-4.5 configure recognized essentially only the --prefix= and
> +--libdir= option to specify target directories. Starting with xen-4.5
> +all paths can be adjusted once with configure.
> +
> +
> +Examples
> +========
> +
> +To build a private copy of tools and xen:
> +configure --prefix=/odd/path --sysconfdir=/odd/path/etc --enable-rpath
> +make
> +sudo make install BOOT_DIR=/ood/path/boot EFI_DIR=/odd/path/efi
> +
> +
> +TODO
> +====
> +
> + - DESTDIR should be empty, not "/"
> + - add make uninstall targets
> + - replace private path variables as needed (SBINDIR/sbindir)
> + - ...
> diff --git a/README b/README
> index 414e5b9..8e5eb5e 100644
> --- a/README
> +++ b/README
> @@ -110,8 +110,7 @@ performed with root privileges.]
>      # make world
>      # make install
>  
> -   If you want, you can run ./configure --help to see the list of
> -   options available options when building and installing Xen.
> +   See the documentation in the INSTALL file for more info.
>  
>     This will create and install onto the local machine. It will build
>     the xen binary (xen.gz), the tools and the documentation.
>
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@xxxxxxxxxxxxx
> http://lists.xen.org/xen-devel


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel