RPCSX/archived-xed
1
0
Fork 0
mirror of https://github.com/RPCSX/xed.git synced 2026-01-31 01:05:17 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
034b7067509d637048ecfb24f9e9bb8ae63b4db3
archived-xed/docsrc/xed-build.txt
Mark Charney 034b706750 xed-buildt.txt doc: python 27 or 34 or later... 
Change-Id: I2414572b27d220506d4ecd0ee5200d32db965f3b
(cherry picked from commit 7383596c14a5cd9d1cf89e2431b3f6c640e48153)
2017-06-20 21:05:59 -04:00

403 lines
15 KiB
Plaintext
Raw Blame History

#BEGIN_LEGAL
#Copyright (c) 2016 Intel Corporation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#END_LEGAL
//
// This file does not contain any code
// it just contains additional information for
// inclusion with doxygen
// ========================================================================================
/*!
@mainpage XED Build Guide
by Mark Charney
2016-12-14
@section INTRO Introduction
XED can build with many compilers:
- GNU Gcc
- Microsoft Visual Studio
- Intel ICL/ICC
- LLVM/Clang
XED also works with the following operating systems:
- Linux
- Microsoft Windows (with or without cygwin)
- Apple Mac OS/X
- FreeBSD
The default compiler on Linux and FreeBSD is GNU gcc. The default on
Windows is to use MSVS. The default compiler on OS X is clang.
The build system uses the compilers from your PATH by default. You can
override this with various command line options.
Table of Contents
- @ref REPOS "REPOS" Repository access
- @ref MBUILD "MBUILD" Using mbuild to build XED
- @ref INSTALL "INSTALL" Making XED kits
- @ref WINDOWS "WINDOWS" Windows notes
- @ref SHARED "SHARED" Shared libraries and DLLs
- @ref HELP "HELP" The mbuild options
@section REPOS Repository Access
XED is stored in an GIT repository. Request access from
me if you want to build XED.
It is a good idea to set up an ssh-agent and cache your private keys
so you do not have to repeatedly type your ssh passphrase when doing the
git clone operations.
Here's how to check out XED and mbuild, as sibling directories:
@if (EXTERNAL)
@code
git clone https://github.com/intelxed/xed.git xed
git clone https://github.com/intelxed/mbuild.git mbuild
@endcode
@else
@code
git clone ssh://git-ger-3.devtools.intel.com:29418/ssgsde-xed xed
git clone ssh://git-ger-3.devtools.intel.com:29418/ssgsde-mbuild mbuild
@endcode
@endif
If you are working in a directory called foo, then after the clones,
your trees should look like this:
@code
|-mbuild-|-mbuild----
foo-| |-tests-----
|
|-xed----|-datafiles-|-avx--------
| |-avxivb-----
| |-avxhsw-----
|-docsrc----
|-enumer.d--
|-examples--
|
|-include---|-private----
| |-public-----
|-misc------
|-scripts---
|
|-tests-----|-test-00000-
| |-test-00001-
...
| |-test-00147-
|-use-------
@endcode
@section MBUILD Introduction to using mbuild
Mbuild is a python-based build system. For more information about mbuild see:
https://intelxed.github.io (or inside Intel http://mjc.intel.com/mjcharne/mbuild ).
The XED build using mbuild is dependence driven It uses file and
command signatures to detect the need to rebuild files.
The mbuild script requires python version 2.7, python 3.4 or later.
Assuming you checked out the tree as described above, you can build
XED using mbuild as follows on linux:
@code
mkdir build
cd build
../xed/mfile.py
../xed/mfile.py examples (optional)
../xed/mfile.py doc (optional, requires doxygen)
../xed/mfile.py doc-build (optional, requires doxygen)
../xed/mfile.py install (optional)
../xed/mfile.py install zip (optional, makes a zip file)
../xed/mfile.py examples install zip (optional, makes a zip file that includes the examples)
@endcode
Actual windows example (password prompts omitted):
@if (EXTERNAL)
@code
git clone https://github.com/intelxed/xed.git xed
git clone https://github.com/intelxed/mbuild.git mbuild
mkdir test
cd test
C:/Python27/python ../xed/mfile.py examples install zip
@endcode
@else
@code
git clone ssh://git-ger-3.devtools.intel.com:29418/ssgsde-xed xed
git clone ssh://git-ger-3.devtools.intel.com:29418/ssgsde-mbuild mbuild
mkdir test
cd test
C:/Python27/python ../xed/mfile.py examples install zip
@endcode
@endif
For more information on building for windows see section @ref WINDOWS
Actual linux example (password prompts omitted):
@if (EXTERNAL)
@code
git clone https://github.com/intelxed/xed.git xed
git clone https://github.com/intelxed/mbuild.git mbuild
mkdir test
cd test
python ../xed/mfile.py examples install zip
@endcode
@else
@code
git clone ssh://git-ger-3.devtools.intel.com:29418/ssgsde-xed xed
git clone ssh://git-ger-3.devtools.intel.com:29418/ssgsde-mbuild mbuild
mkdir test
cd test
python ../xed/mfile.py examples install zip
@endcode
@endif
To build 32b on a 64b platform, add to the mfile.py execution "host_cpu=ia32":
@code
C:/Python27/python ../xed/mfile.py examples install zip host_cpu=ia32
@endcode
@section INSTALL Making XED kits
Some of the headers are private (for building XED), some are public
and some are generated. To simplify use, I recommend that all users
work from XED kits, rather from the XED sources. This section
describes how to build XED kits using the "install" target.
The install target collects up all pieces and puts them in one
subdirectory. The static public headers and dynamically generated
public header files are put in an "include" subdirectory.
Static libraries are put the "lib" directory. If you are doing a
shared object or DLL build, the shared object or DLL is put in the bin
directory. This simplifies using the examples.
The manual and examples, if generated, are also included in doc
directory.
The structure of a XED kit is as follows:
@code
|-bin------
|-doc------|-html-
|-examples-
|-xed-kit-name--|-include--
|-lib------
|-misc-----
@endcode
You can also combine the various targets in one invocation. It will be
quicker than the sequence of commands.
@code
../xed/mfile.py doc doc-build examples install
@endcode
@section WINDOWS Windows notes
For building on windows, the easiest build method assumes that you've
configured your environment by running the appropriate BAT file, such
as vcvars32.bat or vcvarsamd64.bat from the bin directory of your MSVS
installation, by opening a Visual Studio command prompt or by having
installed the compiler environment in to the default environment
during MSVS installation.
On windows you can build from a cmd.exe or a cygwin window, with MSVS or GNU gcc.
@code
/* Run the Visual Studio setup script (vcvars32.bat or vcvarsamd64.bat) from your compiler installation */
C:/Python27/python ../xed/mfile.py examples ( from a cmd.exe window using win32 python)
/* or from cygwin, using MSVS, you must ensure your MSVS compiler environment is set up properly */
../xed/mfile.py examples ( from a cygwin window, using cygwin's python)
/* if you installed the compiler in a standard place, you can have MBUILD set it up*/
C:/Python27/python ../xed/mfile.py --setup-msvs --msvs-version 10 examples
/* or from cygwin, using GCC */
../xed/mfile.py --compiler=gnu examples ( from a cygwin window, using cygwin's gcc)
@endcode
The cygwin builds will use cygwin's python to launch the mfile, but
win32 c:/Python27/python to run the generators. I try to avoid
building using cygwin's python because those builds are single
threaded because of long standing bugs in cygwin.
If you want to have symbols in the xed command line example, you must
build with MSVS 8 (2005) or later and supply the "--dbghelp" option to
the build line. During execution, dbghelp.dll version 6.9.3.113 or
later, is required. Dbghelp.dll must be placed in the same directory
as xed.exe. Dbghelp.dll is available from Microsoft.
@section SHARED Shared libraries and DLLs
If you build XED using the \-\-shared object you'll get a libxed.so on
Linux or a libxed.dll on Windows. When you link against these shared
objects/DLL you are required to define XED_DLL (/DXED_DLL on Windows
or -DXED_DLL on Linux).
@section HELP The mbuild options
If you supply the \-\-help message to the ../xed/mfile.py you'll
see the various options controlling compilation. Some options are
build into to mbuild and are not relevant for the XED0 build (like the
assembler overrides). I've omitted the irrelevant ones in the
following options listing:
@code
% ./mfile.py --help
Usage: mfile.py [options]
Options:
-h, --help show this help message and exit
-j JOBS, --jobs=JOBS Number of concurrent worker threads to use.
--mbuild-version Emit the version information
--build-dir=BUILD_DIR
Build directory, default is 'obj'
--src-dir=SRC_DIR The directory where the sources are located.
--gen-dir=GEN_DIR The directory where generated sources are assumed to
be located.
-v VERBOSE, --verbose=VERBOSE
Verbosity level. Defaults to value passed to env_t()
--compiler=COMPILER Compiler (ms,gnu,clang,icc,icl,iclang). Default is gnu
on linux and ms on windows. Default is: gnu
--debug Debug build
--shared Shared DLL build
--static Statically link executables
--opt=OPT Optimization level noopt, 0, 1, 2, 3
-s, --silent Silence all but the most important messages
--extra-defines=EXTRA_DEFINES
Extra preprocessor defines
--extra-flags=EXTRA_FLAGS
Extra values for CXXFLAGS and CCFLAGS
--extra-cxxflags=EXTRA_CXXFLAGS
Extra values for CXXFLAGS
--extra-ccflags=EXTRA_CCFLAGS
Extra values for CCFLAGS
--extra-linkflags=EXTRA_LINKFLAGS
Extra values for LINKFLAGS
--extra-libs=EXTRA_LIBS
Extra values for LIBS
--toolchain=TOOLCHAIN
Compiler toolchain
--vc-dir=VC_DIR MSVS Compiler VC directory. For finding libraries and
setting the toolchain
--msvs-version=MSVS_VERSION, --msvc-version=MSVS_VERSION, --msvsversion=MSVS_VERSION, --msvcversion=MSVS_VERSION
MSVS version 6=VC98, 7=VS .Net 2003, 8=VS 2005, 9=VS
2008, 10=VS 2010/DEV10, 11=VS2012/DEV11This sets
certain flags and idioms for quirks in some compilers.
--setup-msvc, --setup-msvs, --msvs-setup, --msvc-setup
Use the value of the --msvc-version to initialize the
MSVC configuration.
--icc-version=ICC_VERSION, --iccver=ICC_VERSION, --icc-ver=ICC_VERSION
ICC/ICL version 7, 8, 9, 10, 11
--gcc-version=GCC_VERSION, --gccversion=GCC_VERSION, --gcc-ver=GCC_VERSION
GCC version, with dots as in 2.96, 3.4.3, 4.2.0, etc.
--cc=CC full path to C compiler
--cxx=CXX full path to C++ compiler
--linker=LINKER full path to linker
--ar=AR full path to archiver (lib/ar)
--as=AS full path to assembler (gas/as/ml/ml64)
--yasm Use yasm
--no-cygwin-limit Do not limit cygwin to one job at a time. Default is
to limit cygwin to one job.
--host-cpu=ARG_HOST_CPU
Host CPU, typically ia32, intel64 or x86-64
--host-os=ARG_HOST_OS
Host OS (where the binary runs)
--doxygen-install=DOXYGEN_INSTALL
Doxygen installation directory
--doxygen=DOXYGEN Doxygen command name
-c, --clean Clean targets
-k, --keep-going Keep going after errors occur when building
--messages Enable use xed's debug messages
--asserts Enable use xed's asserts
--clr Compile for Microsoft CLR
--no-werror Disable use of -Werror on GNU compiles
--gen-ild-storage Dump ILD storage data file.
--show-dag Show the dependence DAG
--ext=EXT Add extension files of the form
pattern-name:file-name.txt
--extf=EXTF Add extension configuration files that contain
lines of form pattern-name:file-name.txt. All files
references will be made relative to the directory in
which the config file is located
--default-isa-extf=DEFAULT_ISA
Override the default ISA files.cfg file
--knc Include KNC support
--no-avx Do not include AVX
--no-xsaveopt Do not include XSAVEOPT
--no-ivbavx Do not include AVX for IVB.
--no-ivbint Do not include integer (nonAVX) IVB NI.
--no-avxhsw Do not include AVX for HSW.
--no-mpx Do not include MPX.
--no-sha Do not include SHA.
--no-bdw Do not include BDW NI.
--no-glm Do not include GLM.
--knl Include KNL AVX512{PF,ER} on top of AVX512{F,CD}.
Default: Currently enabled.
--no-knl Do no include KNL AVX512{PF,ER}. Default: KNL enabled.
--no-skl Do not include SKL.
--no-skx Do not include SKX.
--no-memory-future Do not include future memory NI.
--no-avx512-future Do not include future avx512 instructions.
--dbghelp Use dbghelp.dll on windows.
--install-dir=INSTALL_DIR
XED Install directory.
Default: kits/xed-install-date-os-cpu
--kit-kind=KIT_KIND Kit version string.
The default is 'base'
--no-amd Disable AMD public instructions
--limit-strings Remove some strings to save space.
--no-encoder Disable the encoder
--no-decoder Disable the decoder
--generator-options=GENERATOR_OPTIONS
Options to pass through for
the decode generator
--legal-header=LEGAL_HEADER
Use this special legal header
on public header files and examples.
--python=PYTHONARG Use a specific version of python
for subprocesses.
--elf-dwarf, --dwarf Use libelf/libdwarf. (Linux only)
--dev Developer knob. Updates VERSION file
--elf-dwarf-precompiled
Use precompiled libelf/libdwarf from the XED source
distribution. This is the currently required if you
are installing a kit. Implies the --elf-dwarf knob.
(Linux only)
--strip=STRIP Path to strip binary. (Linux only)
--pti-test INTERNAL TESTING OPTION.
--compress-operands use bit-fields to compress the operand storage.
--test-perf Do performance test (on linux). Requires specific
external test binary.
@endcode
*/
Reference in New Issue View Git Blame Copy Permalink