diff options
39 files changed, 1357 insertions, 736 deletions
diff --git a/.gitignore b/.gitignore index 0986bb6e4c..3b0e21bde3 100644 --- a/.gitignore +++ b/.gitignore @@ -86,6 +86,8 @@ lib/os_mon/priv/obj/win32/ lib/runtime_tools/c_src/win32/ lib/runtime_tools/priv/lib/ lib/runtime_tools/priv/obj/ +lib/runtime_tools/doc/src/DTRACE.xml +lib/runtime_tools/doc/src/SYSTEMTAP.xml lib/tools/bin/win32/ lib/tools/c_src/win32/ lib/tools/obj/win32/ @@ -335,6 +337,7 @@ JAVADOC-GENERATED /system/doc/installation_guide/INSTALL.xml /system/doc/installation_guide/INSTALL-CROSS.xml /system/doc/installation_guide/INSTALL-WIN32.xml +/system/doc/installation_guide/MARKDOWN.xml # test_server diff --git a/HOWTO/BENCHMARKS.md b/HOWTO/BENCHMARKS.md new file mode 100644 index 0000000000..361d99256d --- /dev/null +++ b/HOWTO/BENCHMARKS.md @@ -0,0 +1,73 @@ +Benchmarking Erlang/OTP +======================= + +The Erlang/OTP source tree contains a number of benchmarks. The same framework +is used to run these benchmarks as is used to run tests. Therefore in order to +run benchmarks you have to [release the tests][] just as you normally would. + +Note that many of these benchmarks were developed to test a specific feature +under a specific setting. We strive to keep the benchmarks up-to-date, but alas +time is not an endless resource so some benchmarks will be outdated and +irrelevant. + +Running the benchmarks +---------------------- + +As with testing, `ts` is used to run the benchmarks. Before running any +benchmarks you have to [install the tests][]. To get a listing of all +benchmarks you have available call `ts:benchmarks()`. + +To run all benchmarks call `ts:bench()`. This will run all benchmarks using +the emulator which is in you `$PATH` (Note that this does not have to be the +same as from which the benchmarks were built from). All the results of the +benchmarks are put in a folder in `$TESTROOT/test_server/` called +`YYYY_MO_DDTHH_MI_SS`. + +Each benchmark is run multiple times and the data for all runs is collected in +the files within the benchmark folder. All benchmarks are written so that a +higher values are better. + +Writing benchmarks +------------------ + +Benchmarks are just normal testcases in Common Test suites. They are marked as +benchmarks by being included in the `AppName_bench.spec` which is located in +`lib/AppName/test/` for the applications which have benchmarks. Note that you +might want to add a skip clause to `AppName.spec` for the benchmarks if you do +not want them to be run in the nightly tests. + +Results of benchmarks are sent using the ct_event mechanism and automatically +collected and formatted by ts. + + ct_event:notify( + #event{name = benchmark_data, + data = [{value,TPS}]}). + +The application, suite and testcase associated with the value is automatically +detected. If you want to supply your own you can include `suite` andor `name` +with the data. i.e. + + ct_event:notify( + #event{name = benchmark_data, + data = [{suite,"erts_bench"}, + {name,"ets_transactions_per_sec"}, + {value,TPS}]}). + +The reason for using the internal ct_event and not ct is because the benchmark +code has to be backwards compatible with at least R14. + +The value which is reported should be as raw as possible. i.e. you should not +do any averaging of the value before reporting. The tools we use to collect the +benchmark data over time will do averages, means, stddev and more with the data. +So the more data which is sent using `ct_event` the better. + +Viewing benchmarks +------------------ + +At the moment of writing this HOWTO the tool for viewing benchmark results is +not available as opensource. This will hopefully change in the near future. + + + [release the tests]: README.testing.md#releasing-tests + [install the tests]: README.testing.md#configuring-the-test-environment + diff --git a/README.bootstrap b/HOWTO/BOOTSTRAP.md index f42bc7aa47..59e31165cf 100644 --- a/README.bootstrap +++ b/HOWTO/BOOTSTRAP.md @@ -1,16 +1,16 @@ Notes about prebuilt beam files under version control ------------------------------------------------------ +===================================================== This information applies mostly to developers, some parts only to developers of the main branch i.e. Ericsson and HiPE personel. There are two types of derived code under version control, namely: -primary bootstrap - Resides in the $ERL_TOP/bootstrap/{lib,bin} directories. -preloaded code - Resides in the $ERL_TOP/erts/preloaded directory. +primary bootstrap - Resides in the `$ERL_TOP/bootstrap/{lib,bin}` directories. +preloaded code - Resides in the `$ERL_TOP/erts/preloaded` directory. Primary bootstrap -................. +----------------- The two types of version controlled code are fundamentally different. The primary bootstrap is code compiled from source files in @@ -19,7 +19,7 @@ lib/orber/include. They are checked in in the version control system to make it possible to build directly from the code base tree without the need for an earlier version of the compiler. When a new version of OTP is released, these files are updated manually (or rather, by using -the $ERL_TOP/otp_build script) and checked in. The files can also be +the `$ERL_TOP/otp_build` script) and checked in. The files can also be updated due to changes in the compiler during the development process. The primary bootstrap is always updated as a separate deliberate process, never during a normal development build. @@ -27,31 +27,31 @@ deliberate process, never during a normal development build. If a prebuilt open source version of erlang is used, the directory bootstrap initially does not contain any beam files, the directory is instead populated by copying beam files from the -$ERL_TOP/lib/{kernel,stdlib,compiler}/ebin directories. This +`$ERL_TOP/lib/{kernel,stdlib,compiler}/ebin` directories. This construction is to save space in the distribution, but the result would be the same. Open source developers need not provide patches for the precompiled beam files in the primary bootstrap, the bootstrap update is always performed by the main developers. Preloaded code -.............. +-------------- -The directory $ERL_TOP/preloaded contains both src and ebin +The directory `$ERL_TOP/preloaded` contains both src and ebin subdirectories. The preloaded code is compiled into the virtual machine and always present. When compiling the virtual machine, those beam files need to be present and they are considered a part of the virtual machine rather than a part of the kernel application. When preloaded files are to be updated, the source code is built using a -special Makefile in the $ERL_TOP/preloaded/src directory, which +special Makefile in the `$ERL_TOP/preloaded/src` directory, which creates beam files in the same directory. When they seem to compile successfully, they can be used in an emulator build by being copied -to the ebin directory. otp_build update_preloaded can be used to +to the ebin directory. `otp_build update_preloaded` can be used to ease the process (there are also similar targets in the -$ERL_TOP/preloaded/src/Makefile). +`$ERL_TOP/preloaded/src/Makefile`). In prebuilt open source distributions, these beam files are also present, but to update them one might need to change permission on the -$ERL_TOP/preloaded/ebin directory, then build and then manually copy +`$ERL_TOP/preloaded/ebin` directory, then build and then manually copy the beam files from the source directory to ../ebin. If patches are created that involve the source files used to build preloaded code, always note this specially as the preloaded/ebin directory needs diff --git a/README.dtrace.md b/HOWTO/DTRACE.md index 5bc042f9fc..b719c68c59 100644 --- a/README.dtrace.md +++ b/HOWTO/DTRACE.md @@ -5,7 +5,7 @@ History ------- The first implementation of DTrace probes for the Erlang virtual -machine was presented at the [2008 Erlang User Conference] [4]. That +machine was presented at the [2008 Erlang User Conference] [1]. That work, based on the Erlang/OTP R12 release, was discontinued due to what appears to be miscommunication with the original developers. @@ -16,13 +16,13 @@ e.g. `foo_module:dtrace_probe("message goes here!")`. Goals ----- -1. Annotate as much of the Erlang VM as is practical. +* Annotate as much of the Erlang VM as is practical. * The initial goal is to trace file I/O operations. -2. Support all platforms that implement DTrace: OS X, Solaris, - and (I hope) FreeBSD and NetBSD. -3. To the extent that it's practical, support SystemTap on Linux - via DTrace provider compatibility. -4. Allow Erlang code to supply annotations. +* Support all platforms that implement DTrace: OS X, Solaris, + and (I hope) FreeBSD and NetBSD. +* To the extent that it's practical, support SystemTap on Linux + via DTrace provider compatibility. +* Allow Erlang code to supply annotations. Supported platforms ------------------- @@ -33,8 +33,8 @@ Supported platforms OpenIndiana release 151a, and both appear to work. * FreeBSD 9.0, though please see the "FreeBSD 9.0 Release Notes" section below! -* Linux via SystemTap compatibility. Please see the file - `README.systemtap.md` for more details. +* Linux via SystemTap compatibility. Please see + [$ERL_TOP/HOWTO/SYSTEMTAP.md][] for more details. Just add the `--with-dynamic-trace=dtrace` option to your command when you run the `configure` script. If you are using systemtap, the configure option @@ -43,10 +43,10 @@ is `--with-dynamic-trace=systemtap` Status ------ -As of R15B01, the dynamic trace code is included in the main OTP distribution, +As of R15B01, the dynamic trace code is included in the OTP source distribution, although it's considered experimental. The main development of the dtrace code still happens outside of Ericsson, but there is no need to fetch a patched -version of OTP to get the basic funtionality. +version of the OTP source to get the basic funtionality. Implementation summary ---------------------- @@ -66,9 +66,7 @@ following may be executed in a different Pthread: * `efile_drv` command execution (C code) * `efile_drv` status return (C code) -**TODO: keep this description up-to-date.** - -Example output from `lib/dtrace/examples/efile_drv.d` while executing +Example output from `lib/runtime_tools/examples/efile_drv.d` while executing `file:rename("old-name", "new-name")`: efile_drv enter tag={3,84} user tag some-user-tag | RENAME (12) | args: old-name new-name , 0 0 (port #Port<0.59>) @@ -83,7 +81,7 @@ Example output from `lib/dtrace/examples/efile_drv.d` while executing these two numbers form a unique ID for the I/O operation. * `12` is the command number for the rename operation. See the definition for `FILE_RENAME` in the source code file `efile_drv.c` - or the `BEGIN` section of the D script `lib/dtrace/examples/efile_drv.d`. + or the `BEGIN` section of the D script `lib/runtime_tools/examples/efile_drv.d`. * `old-name` and `new-name` are the two string arguments for the source and destination of the `rename(2)` system call. The two integer arguments are unused; the simple formatting code @@ -101,8 +99,8 @@ So, where does the `some-user-tag` string come from? At the moment, the user tag comes from code like the following: - put(dtrace_utag, "some-user-tag"), - file:rename("old-name", "new-name"). + dyntrace:put_tag("some-user-tag"), + file:rename("old-name", "new-name"), This method of tagging I/O at the Erlang level is subject to change. @@ -391,3 +389,4 @@ Guide to efile_drv.c probe arguments probe arg9 = C driver dt_i4 = advise_type; [1]: http://www.erlang.org/euc/08/ + [$ERL_TOP/HOWTO/SYSTEMTAP.md]: SYSTEMTAP.md diff --git a/HOWTO/INSTALL-CROSS.md b/HOWTO/INSTALL-CROSS.md new file mode 100644 index 0000000000..95264a82eb --- /dev/null +++ b/HOWTO/INSTALL-CROSS.md @@ -0,0 +1,556 @@ +Cross Compiling Erlang/OTP +========================== + +Introduction +------------ + +This document describes how to cross compile Erlang/OTP-%OTP-REL%. Note that +the support for cross compiling Erlang/OTP should be considered as +experimental. As far as we know, the %OTP-REL% release should cross compile +fine, but since we currently have a very limited set of cross compilation +environments to test with we cannot be sure. The cross compilation support +will remain in an experimental state until we get a lot more cross compilation +environments to test with. + +You are advised to read the whole document before attempting to cross +compile Erlang/OTP. However, before reading this document, you should read +the [$ERL_TOP/HOWTO/INSTALL.md][] document which describes building and installing +Erlang/OTP in general. `$ERL_TOP` is the top directory in the source tree. + +### otp\_build Versus configure/make ### + +Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build` +script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using +`otp_build` is easier since it involves fewer steps, but the `otp_build` build +procedure is not as flexible as the `configure`/`make` build procedure. Note +that `otp_build configure` will produce a default configuration that differs +from what `configure` will produce by default. For example, currently +`--disable-dynamic-ssl-lib` is added to the `configure` command line arguments +unless `--enable-dynamic-ssl-lib` has been explicitly passed. The binary +releases that we deliver are built using `otp_build`. The defaults used by +`otp_build configure` may change at any time without prior notice. + +### Cross Configuration ### + +The `$ERL_TOP/xcomp/erl-xcomp.conf.template` file contains all available cross +configuration variables and can be used as a template when creating a cross +compilation configuration. All [cross configuration variables][] are also +listed at the end of this document. For examples of working cross +configurations see the `$ERL_TOP/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf` +file and the `$ERL_TOP/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf` file. If the +default behavior of a variable is satisfactory, the variable does not need to +be set. However, the `configure` script will issue a warning when a default +value is used. When a variable has been set, no warning will be issued. + +A cross configuration file can be passed to `otp_build configure` using the +`--xcomp-conf` command line argument. Note that `configure` does not accept +this command line argument. When using the `configure` script directly, pass +the configuration variables as arguments to `configure` using a +`<VARIABLE>=<VALUE>` syntax. Variables can also be passed as environment +variables to `configure`. However, if you pass the configuration in the +environment, make sure to unset all of these environment variables before +invoking `make`; otherwise, the environment variables might set make variables +in some applications, or parts of some applications, and you may end up with +an erroneously configured build. + +### What can be Cross Compiled? ### + +All Erlang/OTP applications except the `wx` application can be cross compiled. +The build of the `wx` driver will currently be automatically disabled when +cross compiling. + +### Compatibility ### + +The build system, including cross compilation configuration variables used, +may be subject to non backward compatible changes without prior notice. +Current cross build system has been tested when cross compiling some Linux/GNU +systems, but has only been partly tested for more esoteric platforms. The +VxWorks example file is highly dependent on our environment and is here more +or less only for internal use. + +### Patches ### + +Please submit any patches for cross compiling in a way consistent with this +system. All input is welcome as we have a very limited set of cross compiling +environments to test with. If a new configuration variable is needed, add it +to `$ERL_TOP/xcomp/erl-xcomp.conf.template`, and use it in `configure.in`. +Other files that might need to be updated are: + +- `$ERL_TOP/xcomp/erl-xcomp-vars.sh` +- `$ERL_TOP/erl-build-tool-vars.sh` +- `$ERL_TOP/erts/aclocal.m4` +- `$ERL_TOP/xcomp/README.md` +- `$ERL_TOP/xcomp/erl-xcomp-*.conf` + +Note that this might be an incomplete list of files that need to be updated. + +General information on how to submit patches can be found at: + <http://wiki.github.com/erlang/otp/submitting-patches> + +Build and Install Procedure +--------------------------- + +If you are building in Git, you want to read the [Building in Git][] section +of [$ERL_TOP/HOWTO/INSTALL.md][] before proceeding. + +We will first go through the `configure`/`make` build procedure which people +probably are most familiar with. + +### Building With configure/make Directly ### + + (1) + +Change directory into the top directory of the Erlang/OTP source tree. + + $ cd $ERL_TOP + +In order to compile Erlang code, a small Erlang bootstrap system has to be +built, or an Erlang/OTP system of the same release as the one being built +has to be provided in the `$PATH`. The Erlang/OTP for the target system will +be built using this Erlang system, together with the cross compilation tools +provided. + +If you want to build the documentation out of the same source tree as you are +cross compiling in, you currently need a full Erlang/OTP system of the same +release as the one being built for the build machine. If this is the case, +build and install one for the build machine (or use one already built) and add +it to the `$PATH` before cross building, and building the documentation. See +the [How to Build the Documentation][] section in the [$ERL_TOP/HOWTO/INSTALL.md][] +document for information on how to build the documentation. + +If you want to build using a compatible Erlang/OTP system in the `$PATH`, +jump to (3). + +#### Building a Bootstrap System #### + + (2) + + $ ./configure --enable-bootstrap-only + $ make + +The `--enable-bootstrap-only` argument to `configure` isn't strictly necessary, +but will speed things up. It will only run `configure` in applications +necessary for the bootstrap, and will disable a lot of things not needed by +the bootstrap system. If you run `configure` without `--enable-boostrap-only` +you also have to run make as `make bootstrap`; otherwise, the whole system will +be built. + +#### Cross Building the System #### + + (3) + + $ ./configure --host=<HOST> --build=<BUILD> [Other Config Args] + $ make + +`<HOST>` is the host/target system that you build for. It does not have to be +a full `CPU-VENDOR-OS` triplet, but can be. The full `CPU-VENDOR-OS` triplet +will be created by executing `$ERL_TOP/erts/autoconf/config.sub <HOST>`. If +`config.sub` fails, you need to be more specific. + +`<BUILD>` should equal the `CPU-VENDOR-OS` triplet of the system that you +build on. If you execute `$ERL_TOP/erts/autoconf/config.guess`, it will in +most cases print the triplet you want to use for this. + +Pass the cross compilation variables as command line arguments to `configure` +using a `<VARIABLE>=<VALUE>` syntax. + +> *NOTE*: You can *not* pass a configuration file using the `--xcomp-conf` +> argument when you invoke `configure` directly. The `--xcomp-conf` argument +> can only be passed to `otp_build configure`. + +`make` will verify that the Erlang/OTP system used when building is of the +same release as the system being built, and will fail if this is not the case. +It is possible, however not recommended, to force the cross compilation even +though the wrong Erlang/OTP system is used. This by invoking `make` like this: +`make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes`. + +> *WARNING*: Invoking `make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes` might fail, +> silently produce suboptimal code, or silently produce erroneous code. + +#### Installing #### + +You can either install using the installation paths determined by `configure` +(4), or install manually using (5). + +##### Installing Using Paths Determined by configure ##### + + (4) + + $ make install DESTDIR=<TEMPORARY_PREFIX> + +`make install` will install at a location specified when doing `configure`. +`configure` arguments specifying where the installation should reside are for +example: `--prefix`, `--exec-prefix`, `--libdir`, `--bindir`, etc. By default +it will install under `/usr/local`. You typically do not want to install your +cross build under `/usr/local` on your build machine. Using [DESTDIR][] +will cause the installation paths to be prefixed by `$DESTDIR`. This makes it +possible to install and package the installation on the build machine without +having to place the installation in the same directory on the build machine as +it should be executed from on the target machine. + +When `make install` has finished, change directory into `$DESTDIR`, package +the system, move it to the target machine, and unpack it. Note that the +installation will only be working on the target machine at the location +determined by `configure`. + +##### Installing Manually ##### + + (5) + + $ make release RELEASE_ROOT=<RELEASE_DIR> + +`make release` will copy what you have built for the target machine to +`<RELEASE_DIR>`. The `Install` script will not be run. The content of +`<RELEASE_DIR>` is what by default ends up in `/usr/local/lib/erlang`. + +The `Install` script used when installing Erlang/OTP requires common Unix +tools such as `sed` to be present in your `$PATH`. If your target system +does not have such tools, you need to run the `Install` script on your +build machine before packaging Erlang/OTP. The `Install` script should +currently be invoked as follows in the directory where it resides +(the top directory): + + $ ./Install [-cross] [-minimal|-sasl] <ERL_ROOT> + +where: + +* `-minimal` Creates an installation that starts up a minimal amount + of applications, i.e., only `kernel` and `stdlib` are started. The + minimal system is normally enough, and is what `make install` uses. +* `-sasl` Creates an installation that also starts up the `sasl` + application. +* `-cross` For cross compilation. Informs the install script that it + is run on the build machine. +* `<ERL_ROOT>` - The absolute path to the Erlang installation to use + at run time. This is often the same as the current working directory, + but does not have to be. It can follow any other path through the file + system to the same directory. + +If neither `-minimal`, nor `-sasl` is passed as argument you will be +prompted. + +You can now either do: + + (6) + +* Decide where the installation should be located on the target machine, + run the `Install` script on the build machine, and package the installed + installation. The installation just need to be unpacked at the right + location on the target machine: + + $ cd <RELEASE_DIR> + $ ./Install -cross [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> + +or: + + (7) + +* Package the installation in `<RELEASE_DIR>`, place it wherever you want + on your target machine, and run the `Install` script on your target + machine: + + $ cd <ABSOLUTE_INSTALL_DIR_ON_TARGET> + $ ./Install [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> + +### Building With the otp\_build Script ### + + (8) + + $ cd $ERL_TOP + + (9) + + $ ./otp_build configure --xcomp-conf=<FILE> [Other Config Args] + +alternatively: + + $ ./otp_build configure --host=<HOST> --build=<BUILD> [Other Config Args] + +If you have your cross compilation configuration in a file, pass it using the +`--xcomp-conf=<FILE>` command line argument. If not, pass `--host=<HOST>`, +`--build=<BUILD>`, and the configuration variables using a `<VARIABLE>=<VALUE>` +syntax on the command line (same as in (3)). Note that `<HOST>` and `<BUILD>` +have to be passed one way or the other; either by using `erl_xcomp_host=<HOST>` +and `erl_xcomp_build=<BUILD>` in the configuration file, or by using the +`--host=<HOST>`, and `--build=<BUILD>` command line arguments. + +`otp_build configure` will configure both for the boostrap system on the +build machine and the cross host system. + + (10) + + $ ./otp_build boot -a + +`otp_build boot -a` will first build a bootstrap system for the build machine +and then do the cross build of the system. + + (11) + + $ ./otp_build release -a <RELEASE_DIR> + +`otp_build release -a` will do the same as (5), and you will after this have +to do a manual install either by doing (6), or (7). + +Testing the cross compiled system +--------------------------------- +Some of the tests that come with erlang use native code to test. This means +that when cross compiling erlang you also have to cross compile test suites +in order to run tests on the target host. To do this you first have to release +the tests as usual. + + $ make release_tests + +or + + $ ./otp_build tests + +The tests will be released into `$ERL_TOP/release/tests`. After releasing the +tests you have to install the tests on the build machine. You supply the same +xcomp file as to `./otp_build` in (9). + + $ cd $ERL_TOP/release/tests/test_server/ + $ $ERL_TOP/bootstrap/bin/erl -eval 'ts:install([{xcomp,"<FILE>"}])' -s ts compile_testcases -s init stop + +You should get a lot of printouts as the testcases are compiled. Once done you +should copy the entire `$ERL_TOP/release/tests` folder to the cross host system. + +Then go to the cross host system and setup the erlang installed in (4) or (5) +to be in your `$PATH`. Then go to what previously was +`$ERL_TOP/release/tests/test_server` and issue the following command. + + $ erl -s ts install -s ts run all_tests -s init stop + +The configure should be skipped and all tests should hopefully pass. For more +details about how to use ts run `erl -s ts help -s init stop` + +Currently Used Configuration Variables +-------------------------------------- + +Note that you cannot define arbitrary variables in a cross compilation +configuration file. Only the ones listed below will be guaranteed to be +visible throughout the whole execution of all `configure` scripts. Other +variables needs to be defined as arguments to `configure` or exported in +the environment. + +### Variables for otp\_build Only ### + +Variables in this section are only used, when configuring Erlang/OTP for +cross compilation using `$ERL_TOP/otp_build configure`. + +> *NOTE*: These variables currently have *no* effect if you configure using +> the `configure` script directly. + +* `erl_xcomp_build` - The build system used. This value will be passed as + `--build=$erl_xcomp_build` argument to the `configure` script. It does + not have to be a full `CPU-VENDOR-OS` triplet, but can be. The full + `CPU-VENDOR-OS` triplet will be created by + `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_build`. If set to `guess`, + the build system will be guessed using + `$ERL_TOP/erts/autoconf/config.guess`. + +* `erl_xcomp_host` - Cross host/target system to build for. This value will + be passed as `--host=$erl_xcomp_host` argument to the `configure` script. + It does not have to be a full `CPU-VENDOR-OS` triplet, but can be. The + full `CPU-VENDOR-OS` triplet will be created by + `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_host`. + +* `erl_xcomp_configure_flags` - Extra configure flags to pass to the + `configure` script. + +### Cross Compiler and Other Tools ### + +If the cross compilation tools are prefixed by `<HOST>-` you probably do +not need to set these variables (where `<HOST>` is what has been passed as +`--host=<HOST>` argument to `configure`). + +All variables in this section can also be used when native compiling. + +* `CC` - C compiler. + +* `CFLAGS` - C compiler flags. + +* `STATIC_CFLAGS` - Static C compiler flags. + +* `CFLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library + search path for the shared libraries. Note that this actually is a + linker flag, but it needs to be passed via the compiler. + +* `CPP` - C pre-processor. + +* `CPPFLAGS` - C pre-processor flags. + +* `CXX` - C++ compiler. + +* `CXXFLAGS` - C++ compiler flags. + +* `LD` - Linker. + +* `LDFLAGS` - Linker flags. + +* `LIBS` - Libraries. + +#### Dynamic Erlang Driver Linking #### + +> *NOTE*: Either set all or none of the `DED_LD*` variables. + +* `DED_LD` - Linker for Dynamically loaded Erlang Drivers. + +* `DED_LDFLAGS` - Linker flags to use with `DED_LD`. + +* `DED_LD_FLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library + search path for shared libraries when linking with `DED_LD`. + +#### Large File Support #### + +> *NOTE*: Either set all or none of the `LFS_*` variables. + +* `LFS_CFLAGS` - Large file support C compiler flags. + +* `LFS_LDFLAGS` - Large file support linker flags. + +* `LFS_LIBS` - Large file support libraries. + +#### Other Tools #### + +* `RANLIB` - `ranlib` archive index tool. + +* `AR` - `ar` archiving tool. + +* `GETCONF` - `getconf` system configuration inspection tool. `getconf` is + currently used for finding out large file support flags to use, and + on Linux systems for finding out if we have an NPTL thread library or + not. + +### Cross System Root Locations ### + +* `erl_xcomp_sysroot` - The absolute path to the system root of the cross + compilation environment. Currently, the `crypto`, `odbc`, `ssh` and + `ssl` applications need the system root. These applications will be + skipped if the system root has not been set. The system root might be + needed for other things too. If this is the case and the system root + has not been set, `configure` will fail and request you to set it. + +* `erl_xcomp_isysroot` - The absolute path to the system root for includes + of the cross compilation environment. If not set, this value defaults + to `$erl_xcomp_sysroot`, i.e., only set this value if the include system + root path is not the same as the system root path. + +### Optional Feature, and Bug Tests ### + +These tests cannot (always) be done automatically when cross compiling. You +usually do not need to set these variables. + +> *WARNING*: Setting these variables wrong may cause hard to detect +> runtime errors. If you need to change these values, *really* make sure +> that the values are correct. + +> *NOTE*: Some of these values will override results of tests performed +> by `configure`, and some will not be used until `configure` is sure that +> it cannot figure the result out. + +The `configure` script will issue a warning when a default value is used. +When a variable has been set, no warning will be issued. + +* `erl_xcomp_after_morecore_hook` - `yes|no`. Defaults to `no`. If `yes`, + the target system must have a working `__after_morecore_hook` that can be + used for tracking used `malloc()` implementations core memory usage. + This is currently only used by unsupported features. + +* `erl_xcomp_bigendian` - `yes|no`. No default. If `yes`, the target system + must be big endian. If `no`, little endian. This can often be + automatically detected, but not always. If not automatically detected, + `configure` will fail unless this variable is set. Since no default + value is used, `configure` will try to figure this out automatically. + +* `erl_xcomp_clock_gettime_cpu_time` - `yes|no`. Defaults to `no`. If `yes`, + the target system must have a working `clock_gettime()` implementation + that can be used for retrieving process CPU time. + +* `erl_xcomp_getaddrinfo` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have a working `getaddrinfo()` implementation that can + handle both IPv4 and IPv6. + +* `erl_xcomp_gethrvtime_procfs_ioctl` - `yes|no`. Defaults to `no`. If `yes`, + the target system must have a working `gethrvtime()` implementation and + is used with procfs `ioctl()`. + +* `erl_xcomp_dlsym_brk_wrappers` - `yes|no`. Defaults to `no`. If `yes`, the + target system must have a working `dlsym(RTLD_NEXT, <S>)` implementation + that can be used on `brk` and `sbrk` symbols used by the `malloc()` + implementation in use, and by this track the `malloc()` implementations + core memory usage. This is currently only used by unsupported features. + +* `erl_xcomp_kqueue` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have a working `kqueue()` implementation that returns a file + descriptor which can be used by `poll()` and/or `select()`. If `no` and + the target system has not got `epoll()` or `/dev/poll`, the kernel-poll + feature will be disabled. + +* `erl_xcomp_linux_clock_gettime_correction` - `yes|no`. Defaults to `yes` on + Linux; otherwise, `no`. If `yes`, `clock_gettime(CLOCK_MONOTONIC, _)` on + the target system must work. This variable is recommended to be set to + `no` on Linux systems with kernel versions less than 2.6. + +* `erl_xcomp_linux_nptl` - `yes|no`. Defaults to `yes` on Linux; otherwise, + `no`. If `yes`, the target system must have NPTL (Native POSIX Thread + Library). Older Linux systems have LinuxThreads instead of NPTL (Linux + kernel versions typically less than 2.6). + +* `erl_xcomp_linux_usable_sigaltstack` - `yes|no`. Defaults to `yes` on Linux; + otherwise, `no`. If `yes`, `sigaltstack()` must be usable on the target + system. `sigaltstack()` on Linux kernel versions less than 2.4 are + broken. + +* `erl_xcomp_linux_usable_sigusrx` - `yes|no`. Defaults to `yes`. If `yes`, + the `SIGUSR1` and `SIGUSR2` signals must be usable by the ERTS. Old + LinuxThreads thread libraries (Linux kernel versions typically less than + 2.2) used these signals and made them unusable by the ERTS. + +* `erl_xcomp_poll` - `yes|no`. Defaults to `no` on Darwin/MacOSX; otherwise, + `yes`. If `yes`, the target system must have a working `poll()` + implementation that also can handle devices. If `no`, `select()` will be + used instead of `poll()`. + +* `erl_xcomp_putenv_copy` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have a `putenv()` implementation that stores a copy of the + key/value pair. + +* `erl_xcomp_reliable_fpe` - `yes|no`. Defaults to `no`. If `yes`, the target + system must have reliable floating point exceptions. + +Copyright and License +--------------------- + +%CopyrightBegin% + +Copyright Ericsson AB 2009-2010. All Rights Reserved. + +The contents of this file are subject to the Erlang Public License, +Version 1.1, (the "License"); you may not use this file except in +compliance with the License. You should have received a copy of the +Erlang Public License along with this software. If not, it can be +retrieved online at http://www.erlang.org/. + +Software distributed under the License is distributed on an "AS IS" +basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +the License for the specific language governing rights and limitations +under the License. + +%CopyrightEnd% + +Modifying This Document +----------------------- + +Before modifying this document you need to have a look at the +[$ERL_TOP/HOWTO/MARKDOWN.md][] document. + + + + [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md + [Building in Git]: INSTALL.md#How-to-Build-and-Install-ErlangOTP_Building-in-Git + [How to Build the Documentation]: INSTALL.md#The-ErlangOTP-Documentation_How-to-Build-the-Documentation + [cross configuration variables]: #Currently-Used-Configuration-Variables + [DESTDIR]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html + [$ERL_TOP/HOWTO/MARKDOWN.md]: MARKDOWN.md + + [?TOC]: true diff --git a/INSTALL-WIN32.md b/HOWTO/INSTALL-WIN32.md index ff253d3dfa..94d3688f23 100644 --- a/INSTALL-WIN32.md +++ b/HOWTO/INSTALL-WIN32.md @@ -1037,10 +1037,11 @@ Modifying This Document ----------------------- Before modifying this document you need to have a look at the -`$ERL_TOP/README.md.txt` document. +[$ERL_TOP/HOWTO/MARKDOWN.md][] document. [1]: http://www.erlang.org/faq.html "mailing lists" + [$ERL_TOP/HOWTO/MARKDOWN.md]: MARKDOWN.md [?TOC]: true diff --git a/INSTALL.md b/HOWTO/INSTALL.md index 70d465831d..4f7c317a47 100644 --- a/INSTALL.md +++ b/HOWTO/INSTALL.md @@ -18,10 +18,10 @@ Erlang/OTP should be possible to build from source on any Unix system, including Mac OS X. This document describes how to native compile Erlang/OTP on Unix. For detailed instructions on how to -* cross compile Erlang/OTP, see the [$ERL_TOP/INSTALL-CROSS.md][] +* cross compile Erlang/OTP, see the [$ERL_TOP/HOWTO/INSTALL-CROSS.md][] document. -* build Erlang/OTP on Windows, see the [$ERL_TOP/INSTALL-WIN32.md][] +* build Erlang/OTP on Windows, see the [$ERL_TOP/HOWTO/INSTALL-WIN32.md][] document. Binary releases for Windows can be found at @@ -708,23 +708,25 @@ the best possible performance, do like this: Install Xcode from the AppStore if it is not already installed. -For Xcode 4.3 you will also need to download "Command Line Tools" -via the Downloads preference pane i Xcode. +If you have Xcode 4.3, or later, you will also need to download +"Command Line Tools" via the Downloads preference pane in Xcode. Some tools may still be lacking or out-of-date, we recommend using [Homebrew](https://github.com/mxcl/homebrew/wiki/installation) or -Macports update those tools. +Macports to update those tools. Install MacPorts (<http://www.macports.org/>). Then: $ sudo port selfupdate $ sudo port install gcc45 +universal -If you want to build the `wx` application, get wxMac-2.8.12 +### Building with wxErlang ### + +If you want to build the `wx` application, you will need to get wxMac-2.8.12 (`wxMac-2.8.12.tar.gz` from -<http://sourceforge.net/projects/wxwindows/files/2.8.12/>) and build: +<http://sourceforge.net/projects/wxwindows/files/2.8.12/>) and install it. -Export the path for MacOSX10.6.sdk, +Export the path for MacOSX10.6.sdk: $ export SDK=/Developer/SDKs/MacOSX10.6.sdk @@ -732,18 +734,20 @@ In Xcode 4.3 the path has changed so use the following instead, $ export SDK=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.6.sdk -Then configure and build wx, +Then configure and build wxMac: $ arch_flags="-arch i386" ./configure CFLAGS="$arch_flags" CXXFLAGS="$arch_flags" CPPFLAGS="$arch_flags" LDFLAGS="$arch_flags" OBJCFLAGS="$arch_flags" OBJCXXFLAGS="$arch_flags" --prefix=/usr/local --with-macosx-sdk="$SDK" --with-macosx-version-min=10.6 --enable-unicode --with-opengl --disable-shared $ make $ sudo make install -To link wx properly we will also need to build and install `wxStyledTextCtrl` +To link wx properly you will also need to build and install `wxStyledTextCtrl`: $ cd contrib/src/stc $ make $ sudo make install +### Finish up ### + Build Erlang with the MacPorts GCC as the main compiler (using `clang` for the Objective-C Cocoa code in the `wx` application): @@ -821,12 +825,12 @@ Modifying This Document ----------------------- Before modifying this document you need to have a look at the -`$ERL_TOP/README.md.txt` document. +[$ERL_TOP/HOWTO/MARKDOWN.md][] document. - [$ERL_TOP/INSTALL-CROSS.md]: INSTALL-CROSS - [$ERL_TOP/INSTALL-WIN32.md]: INSTALL-WIN32 + [$ERL_TOP/HOWTO/INSTALL-CROSS.md]: INSTALL-CROSS.md + [$ERL_TOP/HOWTO/INSTALL-WIN32.md]: INSTALL-WIN32.md [DESTDIR]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html [Building in Git]: #How-to-Build-and-Install-ErlangOTP_Building-in-Git [Pre-built Source Release]: #How-to-Build-and-Install-ErlangOTP_Prebuilt-Source-Release @@ -834,5 +838,6 @@ Before modifying this document you need to have a look at the [html documentation]: http://www.erlang.org/download/otp_doc_html_%OTP-REL%.tar.gz [man pages]: http://www.erlang.org/download/otp_doc_man_%OTP-REL%.tar.gz [the released source tar ball]: http://www.erlang.org/download/otp_src_%OTP-REL%.tar.gz + [$ERL_TOP/HOWTO/MARKDOWN.md]: MARKDOWN.md [?TOC]: true diff --git a/README.md.txt b/HOWTO/MARKDOWN.md index a5a1bf4b7d..42045fb10c 100644 --- a/README.md.txt +++ b/HOWTO/MARKDOWN.md @@ -5,7 +5,7 @@ Introduction ------------ If you are looking for information on how to build and install Erlang/OTP you -want to read the [$ERL_TOP/INSTALL.md][] document instead of this document +want to read the [$ERL_TOP/HOWTO/INSTALL.md][] document instead of this document (where `$ERL_TOP` is the top source directory in the source tree). All files with the `.md` suffix (as well as this file) are ordinary text files @@ -258,7 +258,7 @@ under the License. - [$ERL_TOP/INSTALL.md]: doc/installation_guide:INSTALL + [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md [github]: http://github.com [our github repository]: http://github.com/erlang/otp diff --git a/HOWTO/SYSTEMTAP.md b/HOWTO/SYSTEMTAP.md new file mode 100644 index 0000000000..ce9c0b2f0c --- /dev/null +++ b/HOWTO/SYSTEMTAP.md @@ -0,0 +1,75 @@ +SystemTap and Erlang/OTP +======================== + +Introduction +------------ + +SystemTap is DTrace for Linux. In fact Erlang's SystemTap support +is build using SystemTap's DTrace compatibility's layer. For an +introduction to Erlang DTrace support read [$ERL_TOP/HOWTO/DTRACE.md][]. + +Requisites +---------- + +* Linux Kernel with UTRACE support + + check for UTRACE support in your current kernel: + + # grep CONFIG_UTRACE /boot/config-`uname -r` + CONFIG_UTRACE=y + + Fedora 16 is known to contain UTRACE, for most other Linux distributions + a custom build kernel will be required. + Check Fedora's SystemTap documentation for additional required packages + (e.g. Kernel Debug Symbols) + +* SystemTap > 1.6 + + A the time of writing this, the latest released version of SystemTap is + version 1.6. Erlang's DTrace support requires a MACRO that was introduced + after that release. So either get a newer release or build SystemTap from + git yourself (see: http://sourceware.org/systemtap/getinvolved.html) + +Building Erlang +--------------- + +Configure and build Erlang with SystemTap support: + + # ./configure --with-dynamic-trace=systemtap + whatever args you need + # make + +Testing +------- + +SystemTap, unlike DTrace, needs to know what binary it is tracing and has to +be able to read that binary before it starts tracing. Your probe script +therefor has to reference the correct beam emulator and stap needs to be able +to find that binary. +The examples are written for "beam", but other versions such as "beam.smp" or +"beam.debug.smp" might exist (depending on your configuration). Make sure you +either specify the full the path of the binary in the probe or your "beam" +binary is in the search path. + +All available probes can be listed like this: + + # stap -L 'process("beam").mark("*")' + +or: + + # PATH=/path/to/beam:$PATH stap -L 'process("beam").mark("*")' + + +Probes in the dtrace.so NIF library like this: + + # PATH=/path/to/dtrace/priv/lib:$PATH stap -L 'process("dtrace.so").mark("*")' + +Running SystemTap scripts +------------------------- + +Adjust the process("beam") reference to your beam version and attach the script +to a running "beam" instance: + + # stap /path/to/probe/script/port1.systemtap -x <pid of beam> + + + [$ERL_TOP/HOWTO/DTRACE.md]: DTRACE.md diff --git a/HOWTO/TESTING.md b/HOWTO/TESTING.md new file mode 100644 index 0000000000..34eaa68df8 --- /dev/null +++ b/HOWTO/TESTING.md @@ -0,0 +1,150 @@ +Testing Erlang/OTP +================== + +Before you start testing you need to have the Erlang release which you +are going to test in your path. See [$ERL_TOP/HOWTO/INSTALL.md][] for +instructions on how to build an Erlang release. + +Short version +------------- +Move to the top directory of the Erlang release you want to test, i.e. +cd /ldisk/work/otp + + export ERL_TOP=`pwd` + ./otp_build setup -a + export PATH=`pwd`/bin:$PATH + ./otp_build tests + cd release/tests/test_server + erl -s ts install -s ts run all_tests -s init stop + +Where are the tests +------------------- + +There are a lot of tests which test Erlang/OTP (as of 2012 about 12000) and +they are located in different places throughout the source tree. Below is a list +of the places where you can expect to find tests: + +* $ERL_TOP/lib/AppName/test/ +* $ERL_TOP/erts/test/ +* $ERL_TOP/erts/emulator/test/ +* $ERL_TOP/erts/epmd/test/ + +Writing tests +------------- + +All tests are [common_test][] suites and follow the same pattern as all +[common_test][] suites. However, a couple of corner cases are +handled by a test wrapper called `ts`. `ts` allows the test writer to put +`Makefile.src` and `Makefile.first` files in the [data_dir][] and a special +directory called `all_SUITE_data`. + +`Makefile.first` is run before any other Makefile and is typically used to +generate .hrl files which are needed by other test suites. At the moment only +the erl_interface tests use this feature and it should remain that way. + +`Makefile.src` is configured to a `Makefile` using the `variables` created when +[configuring the tests][]. These `Makefile`s are later run by the test suite +to compile whatever platform specific code the tests need to run. + +Releasing tests +--------------- + +If you cannot use [ct_run][] in the source tree you have to release the tests +into a common test directory. The easiest way to do this is to use `otp_build` +like this: + + export ERL_TOP=`pwd`; ./otp_build tests + +This will release all tests in Erlang/OTP to `$ERL_TOP/release/tests/`. If you +want to change the directory where the tests are released to use the `TESTROOT` +environmental variable. + +In the `$TESTROOT` you should now see *_test folders. These folders contain +everything needed to test Erlang/OTP and are platform independent; if you are +testing Erlang on multiple platforms you just have to release on one and copy +the tests to all other platforms. + +### Releasing cross tests + +For releasing tests in a cross compilation environment see [$ERL_TOP/HOWTO/INSTALL-CROSS.md][]. + +Configuring and Running tests +----------------------------- + +Running tests is done by first navigating to the `$TESTROOT/test_server` folder +created when you released the tests and then start `erl` in that directory. The +emulator flags specified will be used in the test runs. For example, if you want +to test using async threads you have to supply `+A 10` to `erl` when you start it. + +To configure and run the tests `ts` is used. `ts` is a wrapper module to +[common_test][] which takes care of configuration and build issues before +[common_test][] is started. + +`ts` has a lot of special options and functions which can be usefull when +testing Erlang/OTP. For a full listing issue `ts:help()` in the erlang shell. + +### Configuring the test environment + +Before running released tests you have to install them on the target system. +Installing the tests is done by calling `ts:install().` in the Erlang shell +which you intend to test from. `ts:install()` is basically a wrapper to a +configure script and some Erlang code which figures out what your system looks +like and what kind of emulator you are testing with. `ts:install()` can also +take some arguments if necessary, see `ts:help()` for details. + +All variables created by `ts:install()` are found in +`$TESTROOT/test_server/variables`. + +### Running the tests + +To run all test suites go to `$TESTROOT/test_server` fire up an Erlang shell and type: + + ts:run(). + +Note that running all tests will require several hours, so you may want to run +the test cases for a single application + + ts:run(Application, [batch]). + +or even part of the test suite for an application, for example + + ts:run(emulator, bs, [batch]). + +to run all test suite modules starting with `bs` (i.e. all modules that test +the bit syntax). + +To run a specific test case in a module, the full name of the module and test +case must be specified: + + ts:run(emulator, bs_bincomp_SUITE, byte_aligned, [batch]). + +Run `ts:help().` for more information. + +As of R14B02 it is also possibly to start all tests but the erl_interface tests +by invoking Common Test directly from the released applications test directory, +i.e. + + cd $TESTROOT/test_server + $ERL_TOP/bin/ct_run -suite ../compiler_test/andor_SUITE -case t_orelse + +Running [ct_run][] from the command line still requires you to do the +`ts:install()` step above. + +Examining the results +--------------------- + +Open the file `release/tests/test_server/index.html` in a web browser. Or open +`release/tests/test_server/last_test.html` when a test suite is running to +examine the results so far for the currently executing test suite (in R14B02 and +later you want to open the `release/tests/test_server/all_runs.html` file to +get to the currently running test) + + [ct_run]: http://www.erlang.org/doc/man/ct_run.html + [ct hook]: http://www.erlang.org/doc/apps/common_test/ct_hooks_chapter.html + [$ERL_TOP/HOWTO/INSTALL.md]: INSTALL.md + [$ERL_TOP/HOWTO/INSTALL-CROSS.md]: INSTALL-CROSS.md#testing-the-cross-compiled-system + [common_test]: http://www.erlang.org/doc/man/ct.html + [data_dir]: http://www.erlang.org/doc/apps/common_test/write_test_chapter.html#data_priv_dir + [configuring the tests]: #configuring-the-test-environment + + [?TOC]: true diff --git a/INSTALL-CROSS.md b/INSTALL-CROSS.md deleted file mode 120000 index 9e7743b9de..0000000000 --- a/INSTALL-CROSS.md +++ /dev/null @@ -1 +0,0 @@ -xcomp/README.md
\ No newline at end of file @@ -18,7 +18,7 @@ Building and Installing ----------------------- Information on building and installing Erlang/OTP can be found -in the `INSTALL.md` document. +in the [$ERL_TOP/HOWTO/INSTALL.md][] document. Contributing to Erlang/OTP -------------------------- @@ -74,3 +74,4 @@ Copyright and License [1]: http://www.erlang.org [2]: http://wiki.github.com/erlang/otp/submitting-patches [3]: http://www.erlang.org/faq.html + [$ERL_TOP/HOWTO/INSTALL.md]: HOWTO/INSTALL.md diff --git a/README.systemtap.md b/README.systemtap.md deleted file mode 100644 index c190bcc893..0000000000 --- a/README.systemtap.md +++ /dev/null @@ -1,72 +0,0 @@ -SystemTap and Erlang/OTP -======================== - -Introduction ------------- - -SystemTap is DTrace for Linux. In fact Erlang's SystemTap support -is build using SystemTap's DTrace compatibility's layer. For an -introduction to Erlang DTrace support read README.dtrace.md. - -Requisites ----------- - -* Linux Kernel with UTRACE support - - check for UTRACE support in your current kernel: - - # grep CONFIG_UTRACE /boot/config-`uname -r` - CONFIG_UTRACE=y - - Fedora 16 is known to contain UTRACE, for most other Linux distributions - a custom build kernel will be required. - Check Fedora's SystemTap documentation for additional required packages - (e.g. Kernel Debug Symbols) - -* SystemTap > 1.6 - - A the time of writing this, the latest released version of SystemTap is - version 1.6. Erlang's DTrace support requires a MACRO that was introduced - after that release. So either get a newer release or build SystemTap from - git yourself (see: http://sourceware.org/systemtap/getinvolved.html) - -Building Erlang ---------------- - -Configure and build Erlang with SystemTap support: - - # ./configure --with-dynamic-trace=systemtap + whatever args you need - # make - -Testing -------- - -SystemTap, unlike DTrace, needs to know what binary it is tracing and has to -be able to read that binary before it starts tracing. Your probe script -therefor has to reference the correct beam emulator and stap needs to be able -to find that binary. -The examples are written for "beam", but other versions such as "beam.smp" or -"beam.debug.smp" might exist (depending on your configuration). Make sure you -either specify the full the path of the binary in the probe or your "beam" -binary is in the search path. - -All available probes can be listed like this: - - # stap -L 'process("beam").mark("*")' - -or: - - # PATH=/path/to/beam:$PATH stap -L 'process("beam").mark("*")' - - -Probes in the dtrace.so NIF library like this: - - # PATH=/path/to/dtrace/priv/lib:$PATH stap -L 'process("dtrace.so").mark("*")' - -Running SystemTap scripts -------------------------- - -Adjust the process("beam") reference to your beam version and attach the script -to a running "beam" instance: - - # stap /path/to/probe/script/port1.systemtap -x <pid of beam> diff --git a/TAR.include b/TAR.include index 5146458eea..87854d24c7 100644 --- a/TAR.include +++ b/TAR.include @@ -2,10 +2,10 @@ AUTHORS EPLICENCE Makefile.in README.md -README.md.txt -INSTALL.md -INSTALL-CROSS.md -INSTALL-WIN32.md +HOWTO/MARKDOWN.md +HOWTO/INSTALL.md +HOWTO/INSTALL-CROSS.md +HOWTO/INSTALL-WIN32.md configure.in aclocal.m4 otp_build diff --git a/erts/emulator/beam/erlang_dtrace.d b/erts/emulator/beam/erlang_dtrace.d index c1024dafc4..ac9b0052e5 100644 --- a/erts/emulator/beam/erlang_dtrace.d +++ b/erts/emulator/beam/erlang_dtrace.d @@ -639,9 +639,9 @@ provider erlang { * Entry into the efile_drv.c file I/O driver * * For a list of command numbers used by this driver, see the section - * "Guide to probe arguments" in ../../../README.md. That section - * also contains explanation of the various integer and string - * arguments that may be present when any particular probe fires. + * "Guide to efile_drv.c probe arguments" in ../../../HOWTO/DTRACE.md. + * That section also contains explanation of the various integer and + * string arguments that may be present when any particular probe fires. * * NOTE: Not all Linux platforms (using SystemTap) can support * arguments beyond arg9. diff --git a/erts/emulator/test/Makefile b/erts/emulator/test/Makefile index 65e0606f98..7af7e48bbd 100644 --- a/erts/emulator/test/Makefile +++ b/erts/emulator/test/Makefile @@ -138,9 +138,10 @@ TARGET_FILES = $(MODULES:%=$(EBIN)/%.$(EMULATOR)) EMAKEFILE=Emakefile -TEST_SPEC_FILES = emulator.spec \ - emulator.spec.win \ - emulator.spec.ose +TEST_SPEC_FILES= emulator.spec \ + emulator.spec.win \ + emulator_bench.spec + # ---------------------------------------------------- # Release directory specification # ---------------------------------------------------- diff --git a/erts/emulator/test/emulator_bench.spec b/erts/emulator/test/emulator_bench.spec new file mode 100644 index 0000000000..f709d913b7 --- /dev/null +++ b/erts/emulator/test/emulator_bench.spec @@ -0,0 +1 @@ +{groups,"../emulator_test",estone_SUITE,[estone_bench]}. diff --git a/erts/emulator/test/estone_SUITE.erl b/erts/emulator/test/estone_SUITE.erl index 2417d4bcfe..21834bfa62 100644 --- a/erts/emulator/test/estone_SUITE.erl +++ b/erts/emulator/test/estone_SUITE.erl @@ -19,7 +19,7 @@ -module(estone_SUITE). %% Test functions -export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1, - init_per_group/2,end_per_group/2,estone/1]). + init_per_group/2,end_per_group/2,estone/1,estone_bench/1]). -export([init_per_testcase/2, end_per_testcase/2]). %% Internal exports for EStone tests @@ -46,6 +46,7 @@ -include_lib("test_server/include/test_server.hrl"). +-include_lib("common_test/include/ct_event.hrl"). %% Test suite defines -define(default_timeout, ?t:minutes(10)). @@ -80,7 +81,7 @@ all() -> [estone]. groups() -> - []. + [{estone_bench, [{repeat,50}],[estone_bench]}]. init_per_suite(Config) -> Config. @@ -108,6 +109,17 @@ estone(Config) when is_list(Config) -> ?line {comment,Mhz ++ " MHz, " ++ integer_to_list(Stones) ++ " ESTONES"}. +estone_bench(Config) -> + DataDir = ?config(data_dir,Config), + L = ?MODULE:macro(?MODULE:micros(),DataDir), + [ct_event:notify( + #event{name = benchmark_data, + data = [{name,proplists:get_value(title,Mark)}, + {value,proplists:get_value(estones,Mark)}]}) + || Mark <- L], + L. + + %% %% Calculate CPU speed %% diff --git a/lib/common_test/doc/src/ct_hooks_chapter.xml b/lib/common_test/doc/src/ct_hooks_chapter.xml index 1dbb841fb0..014507c886 100644 --- a/lib/common_test/doc/src/ct_hooks_chapter.xml +++ b/lib/common_test/doc/src/ct_hooks_chapter.xml @@ -453,7 +453,7 @@ terminate(State) -> <cell>Captures all test results and outputs them as surefire XML into a file. The file which is created is by default called junit_report.xml. The name can be by setting the path option for this hook. e.g. - <code>-ct_hooks cth_surefix [{path,"/tmp/report.xml"}]</code> + <code>-ct_hooks cth_surefire [{path,"/tmp/report.xml"}]</code> Surefire XML can forinstance be used by Jenkins to display test results.</cell> </row> diff --git a/lib/common_test/src/ct.erl b/lib/common_test/src/ct.erl index 571d99029f..6373634812 100644 --- a/lib/common_test/src/ct.erl +++ b/lib/common_test/src/ct.erl @@ -66,7 +66,8 @@ capture_start/0, capture_stop/0, capture_get/0, capture_get/1, fail/1, fail/2, comment/1, comment/2, make_priv_dir/0, testcases/2, userdata/2, userdata/3, - timetrap/1, get_timetrap_info/0, sleep/1]). + timetrap/1, get_timetrap_info/0, sleep/1, + notify/2, sync_notify/2]). %% New API for manipulating with config handlers -export([add_config/2, remove_config/2]). @@ -1047,3 +1048,27 @@ sleep({seconds,Ss}) -> sleep(trunc(Ss * 1000)); sleep(Time) -> test_server:adjusted_sleep(Time). + +%%%----------------------------------------------------------------- +%%% @spec notify(Name,Data) -> ok +%%% Name = atom() +%%% Data = term() +%%% +%%% @doc <p>Sends a asynchronous notification of type <c>Name</c> with +%%% <c>Data</c>to the common_test event manager. This can later be +%%% caught by any installed event manager. </p> +%%% @see //stdlib/gen_event +notify(Name,Data) -> + ct_event:notify(Name, Data). + +%%%----------------------------------------------------------------- +%%% @spec sync_notify(Name,Data) -> ok +%%% Name = atom() +%%% Data = term() +%%% +%%% @doc <p>Sends a synchronous notification of type <c>Name</c> with +%%% <c>Data</c>to the common_test event manager. This can later be +%%% caught by any installed event manager. </p> +%%% @see //stdlib/gen_event +sync_notify(Name,Data) -> + ct_event:sync_notify(Name, Data). diff --git a/lib/common_test/src/ct_event.erl b/lib/common_test/src/ct_event.erl index 3e79898ad1..998be35fda 100644 --- a/lib/common_test/src/ct_event.erl +++ b/lib/common_test/src/ct_event.erl @@ -31,7 +31,7 @@ %% API -export([start_link/0, add_handler/0, add_handler/1, stop/0]). --export([notify/1, sync_notify/1]). +-export([notify/1, notify/2, sync_notify/1,sync_notify/2]). -export([is_alive/0]). %% gen_event callbacks @@ -90,6 +90,13 @@ notify(Event) -> end. %%-------------------------------------------------------------------- +%% Function: notify(Name,Data) -> ok +%% Description: Asynchronous notification to event manager. +%%-------------------------------------------------------------------- +notify(Name, Data) -> + notify(#event{ name = Name, data = Data}). + +%%-------------------------------------------------------------------- %% Function: sync_notify(Event) -> ok %% Description: Synchronous notification to event manager. %%-------------------------------------------------------------------- @@ -102,6 +109,13 @@ sync_notify(Event) -> end. %%-------------------------------------------------------------------- +%% Function: sync_notify(Name,Data) -> ok +%% Description: Synchronous notification to event manager. +%%-------------------------------------------------------------------- +sync_notify(Name,Data) -> + sync_notify(#event{ name = Name, data = Data}). + +%%-------------------------------------------------------------------- %% Function: is_alive() -> true | false %% Description: Check if Event Manager is alive. %%-------------------------------------------------------------------- diff --git a/lib/common_test/src/cth_surefire.erl b/lib/common_test/src/cth_surefire.erl index c42f956b3a..d04a8b07db 100644 --- a/lib/common_test/src/cth_surefire.erl +++ b/lib/common_test/src/cth_surefire.erl @@ -49,9 +49,12 @@ init(Path, Opts) -> properties = proplists:get_value(properties,Opts,[]), timer = now() }. -pre_init_per_suite(Suite,Config,State) -> +pre_init_per_suite(Suite,Config,#state{ test_cases = [] } = State) -> {Config, init_tc(State#state{ curr_suite = Suite, curr_suite_ts = now() }, - Config) }. + Config) }; +pre_init_per_suite(Suite,Config,State) -> + %% Have to close the previous suite + pre_init_per_suite(Suite,Config,close_suite(State)). post_init_per_suite(_Suite,Config, Result, State) -> {Result, end_tc(init_per_suite,Config,Result,State)}. @@ -59,11 +62,7 @@ post_init_per_suite(_Suite,Config, Result, State) -> pre_end_per_suite(_Suite,Config,State) -> {Config, init_tc(State, Config)}. post_end_per_suite(_Suite,Config,Result,State) -> - NewState = end_tc(end_per_suite,Config,Result,State), - TCs = NewState#state.test_cases, - Suite = get_suite(NewState, TCs), - {Result, State#state{ test_cases = [], - test_suites = [Suite | State#state.test_suites]}}. + {Result, end_tc(end_per_suite,Config,Result,State)}. pre_init_per_group(Group,Config,State) -> {Config, init_tc(State#state{ curr_group = [Group|State#state.curr_group]}, @@ -90,7 +89,12 @@ on_tc_fail(_TC, Res, State) -> {fail,lists:flatten(io_lib:format("~p",[Res]))} }, State#state{ test_cases = [NewTC | tl(TCs)]}. +on_tc_skip(Tc,{Type,Reason} = Res, State) when Type == tc_auto_skip -> + do_tc_skip(Res, end_tc(Tc,[],Res,init_tc(State,[]))); on_tc_skip(_Tc, Res, State) -> + do_tc_skip(Res, State). + +do_tc_skip(Res, State) -> TCs = State#state.test_cases, TC = hd(State#state.test_cases), NewTC = TC#testcase{ @@ -98,9 +102,11 @@ on_tc_skip(_Tc, Res, State) -> {skipped,lists:flatten(io_lib:format("~p",[Res]))} }, State#state{ test_cases = [NewTC | tl(TCs)]}. +init_tc(State, Config) when is_list(Config) == false -> + State#state{ timer = now(), tc_log = "" }; init_tc(State, Config) -> State#state{ timer = now(), - tc_log = proplists:get_value(tc_logfile, Config)}. + tc_log = proplists:get_value(tc_logfile, Config, [])}. end_tc(Func, Config, Res, State) when is_atom(Func) -> end_tc(atom_to_list(Func), Config, Res, State); @@ -118,26 +124,35 @@ end_tc(Name, _Config, _Res, State = #state{ curr_suite = Suite, name = Name, time = TimeTakes, failure = passed }| State#state.test_cases]}. - -get_suite(State, TCs) -> +close_suite(#state{ test_cases = [] } = State) -> + State; +close_suite(#state{ test_cases = TCs } = State) -> Total = length(TCs), Succ = length(lists:filter(fun(#testcase{ failure = F }) -> F == passed end,TCs)), Fail = Total - Succ, TimeTaken = timer:now_diff(now(),State#state.curr_suite_ts) / 1000000, - #testsuite{ name = atom_to_list(State#state.curr_suite), - package = State#state.package, - time = io_lib:format("~f",[TimeTaken]), - timestamp = now_to_string(State#state.curr_suite_ts), - errors = Fail, tests = Total, testcases = lists:reverse(TCs) }. - -terminate(State) -> - {ok,D} = file:open(State#state.filepath,[write]), + Suite = #testsuite{ name = atom_to_list(State#state.curr_suite), + package = State#state.package, + time = io_lib:format("~f",[TimeTaken]), + timestamp = now_to_string(State#state.curr_suite_ts), + errors = Fail, tests = Total, + testcases = lists:reverse(TCs) }, + State#state{ test_cases = [], + test_suites = [Suite | State#state.test_suites]}. + +terminate(State = #state{ test_cases = [] }) -> + {ok,D} = file:open(State#state.filepath,[write,{encoding,utf8}]), io:format(D, "<?xml version=\"1.0\" encoding= \"UTF-8\" ?>", []), io:format(D, to_xml(State), []), catch file:sync(D), - catch file:close(D). + catch file:close(D); +terminate(State) -> + %% Have to close the last suite + terminate(close_suite(State)). + + to_xml(#testcase{ group = Group, classname = CL, log = L, name = N, time = T, timestamp = TS, failure = F}) -> ["<testcase ", diff --git a/lib/mnesia/examples/mnesia_tpcb.erl b/lib/mnesia/examples/mnesia_tpcb.erl index 903c53a21c..f36b43a495 100644 --- a/lib/mnesia/examples/mnesia_tpcb.erl +++ b/lib/mnesia/examples/mnesia_tpcb.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2009. All Rights Reserved. +%% Copyright Ericsson AB 1996-2010. All Rights Reserved. %% %% The contents of this file are subject to the Erlang Public License, %% Version 1.1, (the "License"); you may not use this file except in @@ -99,9 +99,13 @@ replica_test/1, sticky_replica_test/1, remote_test/1, - remote_frag2_test/1 + remote_frag2_test/1, + + conflict_benchmark/1 ]). +-include_lib("common_test/include/ct_event.hrl"). + -define(SECOND, 1000000). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -191,8 +195,10 @@ driver_nodes = [node()], n_drivers_per_node = 1, use_running_mnesia = false, + seed, stop_after = timer:minutes(15), % Minimum 15 min report_interval = timer:minutes(1), + send_bench_report = false, use_sticky_locks = false, spawn_near_branch = false, activity_type = transaction, @@ -397,8 +403,30 @@ config(remote_frag2_test, ReplicaType) -> {stop_after, timer:minutes(1)}, {report_interval, timer:seconds(10)}, {reuse_history_id, true} + ]; + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% Ten drivers per node, tables replicated to all nodes, single branch + +config(conflict_benchmark, ReplicaType) -> + Remote = nodes(), + Local = node(), + Nodes = [Local | Remote], + [{seed, {1326,448637,337711}}, + {db_nodes, Nodes}, + {driver_nodes, Nodes}, + {replica_nodes, Nodes}, + {n_drivers_per_node, 10}, + {n_branches, 1}, + {n_accounts_per_branch, 10}, + {replica_type, ReplicaType}, + {stop_after, timer:minutes(1)}, + {report_interval, timer:seconds(10)}, + {send_bench_report, true}, + {reuse_history_id, true} ]. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% start(What, ReplicaType) -> @@ -422,6 +450,9 @@ remote_test(ReplicaType) -> remote_frag2_test(ReplicaType) -> start(remote_frag2_test, ReplicaType). +conflict_benchmark(ReplicaType) -> + start(config(conflict_benchmark, ReplicaType)). + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Args is a list of {Key, Val} tuples where Key is a field name %% in either the record tab_config or run_config. Unknown keys are ignored. @@ -866,6 +897,7 @@ add_time(Acc, New) -> show_report(State) -> Now = now_to_micros(erlang:now()), Iters = State#reporter_state.n_iters, + Cfg = State#reporter_state.run_config, Time = State#reporter_state.curr, Max = Time#time.max_time, N = Time#time.n_trans, @@ -888,7 +920,17 @@ show_report(State) -> "duration of longest transaction was ~p milliseconds~n", [Tps, BruttoTps, Max div 1000]) end, - State#reporter_state{prev_tps = Tps, prev_micros = Now}. + case Cfg#run_config.send_bench_report of + true -> + ct_event:notify( + #event{name = benchmark_data, + data = [{suite,"mnesia_tpcb"}, + {value,Tps}]}); + _ -> + ok + end, + + State#reporter_state{prev_tps = Tps, prev_micros = Now}. signed_diff(Iters, Curr, Prev) -> case Iters > 1 of @@ -955,7 +997,13 @@ alloc_local_branches([], Specs, OrphanBranches) -> {Specs, OrphanBranches}. driver_init(DS, AllBranches) -> - Seed = erlang:now(), + case (DS#driver_state.run_config)#run_config.seed of + undefined -> + Seed = erlang:now(); + Seed -> + Seed + end, + DS2 = if DS#driver_state.n_local_branches =:= 0 -> diff --git a/lib/mnesia/test/Makefile b/lib/mnesia/test/Makefile index 0451da697d..32453bc74e 100644 --- a/lib/mnesia/test/Makefile +++ b/lib/mnesia/test/Makefile @@ -26,6 +26,7 @@ include $(ERL_TOP)/make/$(TARGET)/otp.mk MODULES= \ mt \ mnesia_SUITE \ + mnesia_bench_SUITE \ mnesia_test_lib \ mnesia_install_test \ mnesia_registry_test \ @@ -117,7 +118,7 @@ release_spec: opt release_tests_spec: opt $(INSTALL_DIR) "$(RELSYSDIR)" - $(INSTALL_DATA) mnesia.spec mnesia.cover $(ERL_FILES) $(HRL_FILES) "$(RELSYSDIR)" + $(INSTALL_DATA) mnesia.spec mnesia_bench.spec mnesia.cover $(ERL_FILES) $(HRL_FILES) "$(RELSYSDIR)" $(INSTALL_SCRIPT) mt $(INSTALL_PROGS) "$(RELSYSDIR)" # chmod -R u+w "$(RELSYSDIR)" # @tar cf - *_SUITE_data | (cd "$(RELSYSDIR)"; tar xf -) diff --git a/lib/mnesia/test/mnesia_bench.spec b/lib/mnesia/test/mnesia_bench.spec new file mode 100644 index 0000000000..7b17cb5c4e --- /dev/null +++ b/lib/mnesia/test/mnesia_bench.spec @@ -0,0 +1 @@ +{suites,"../mnesia_test",[mnesia_bench_SUITE]}.
\ No newline at end of file diff --git a/lib/mnesia/test/mnesia_bench_SUITE.erl b/lib/mnesia/test/mnesia_bench_SUITE.erl new file mode 100644 index 0000000000..7cbf77f046 --- /dev/null +++ b/lib/mnesia/test/mnesia_bench_SUITE.erl @@ -0,0 +1,69 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2012. All Rights Reserved. +%% +%% The contents of this file are subject to the Erlang Public License, +%% Version 1.1, (the "License"); you may not use this file except in +%% compliance with the License. You should have received a copy of the +%% Erlang Public License along with this software. If not, it can be +%% retrieved online at http://www.erlang.org/. +%% +%% Software distributed under the License is distributed on an "AS IS" +%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +%% the License for the specific language governing rights and limitations +%% under the License. +%% +%% %CopyrightEnd% +%% + +%% +-module(mnesia_bench_SUITE). +-author('[email protected]'). +-compile(export_all). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +suite() -> [{ct_hooks,[{ts_install_cth,[{nodenames,2}]}]}]. + + +all() -> + [{group,tpcb}]. + +groups() -> + [{tpcb,[{repeat,2}],[tpcb_conflict_ramcopies, + tpcb_conflict_disk_only_copies]}]. + +init_per_group(_GroupName, Config) -> + Config. + +end_per_group(_GroupName, Config) -> + Config. + +init_per_suite(Config) -> + Config. + +end_per_suite(Config) -> + Config. + +init_per_testcase(_Func, Conf) -> + Conf. + +end_per_testcase(_Func, _Conf) -> + ok. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +tpcb_conflict_ramcopies(_Config) -> + mnesia_tpcb:conflict_benchmark(ram_copies). + +tpcb_conflict_disk_only_copies(_Config) -> + mnesia_tpcb:conflict_benchmark(disc_only_copies). + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + + + + + diff --git a/lib/runtime_tools/doc/src/Makefile b/lib/runtime_tools/doc/src/Makefile index d240b287c3..51d93df418 100644 --- a/lib/runtime_tools/doc/src/Makefile +++ b/lib/runtime_tools/doc/src/Makefile @@ -43,9 +43,11 @@ XML_APPLICATION_FILES = ref_man.xml XML_REF3_FILES = dbg.xml dyntrace.xml erts_alloc_config.xml XML_REF6_FILES = runtime_tools_app.xml -XML_PART_FILES = part_notes.xml part_notes_history.xml +XML_PART_FILES = part_notes.xml part_notes_history.xml part.xml XML_CHAPTER_FILES = notes.xml notes_history.xml +GENERATED_XML_FILES = DTRACE.xml SYSTEMTAP.xml + BOOK_FILES = book.xml XML_FILES = \ @@ -78,6 +80,11 @@ DVIPS_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- +$(XML_FILES): $(GENERATED_XML_FILES) + +%.xml: $(ERL_TOP)/HOWTO/%.md $(ERL_TOP)/make/emd2exml + $(ERL_TOP)/make/emd2exml $< $@ + $(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ diff --git a/lib/runtime_tools/doc/src/book.xml b/lib/runtime_tools/doc/src/book.xml index 3f0dd7d55e..ad7d709644 100644 --- a/lib/runtime_tools/doc/src/book.xml +++ b/lib/runtime_tools/doc/src/book.xml @@ -34,6 +34,9 @@ <preamble> <contents level="2"></contents> </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> <applications> <xi:include href="ref_man.xml"/> </applications> diff --git a/lib/runtime_tools/doc/src/dyntrace.xml b/lib/runtime_tools/doc/src/dyntrace.xml index 5fc5530f25..f0149d0665 100644 --- a/lib/runtime_tools/doc/src/dyntrace.xml +++ b/lib/runtime_tools/doc/src/dyntrace.xml @@ -42,7 +42,7 @@ </list> <p>Both building with dynamic trace probes and using them is experimental and unsupported by Erlang/OTP. It is included as an option for the developer to trace and debug performance issues in their systems.</p> <p>The original implementation is mostly done by Scott Lystiger Fritchie as an Open Source Contribution and it should be viewed as such even though the source for dynamic tracing as well as this module is included in the main distribution. However, the ability to use dynamic tracing of the virtual machine is a very valuable contribution which OTP has every intention to maintain as a tool for the developer.</p> - <p>How to write <c>d</c> programs or <c>systemtap</c> scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <c>README.dtrace(.md)</c> and <c>README.systemtap(.md)</c> files in the Erlang source top directory.</p> + <p>How to write <c>d</c> programs or <c>systemtap</c> scripts can be learned from books and from a lot of pages on the Internet. This manual page does not include any documentation about using the dynamic trace tools of respective platform. The <c>examples</c> directory of the <c>runtime_tools</c> application however contains comprehensive examples of both <c>d</c> and <c>systemtap</c> programs that will help you get started. Another source of information is the <seealso marker="DTRACE">dtrace</seealso> and <seealso marker="SYSTEMTAP">systemtap</seealso> chapters in the Runtime Tools Users' Guide.</p> </description> <funcs> <func> diff --git a/lib/runtime_tools/doc/src/part.xml b/lib/runtime_tools/doc/src/part.xml new file mode 100644 index 0000000000..948d4a8020 --- /dev/null +++ b/lib/runtime_tools/doc/src/part.xml @@ -0,0 +1,42 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2012</year><year>2012</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Runtime Tools User's Guide</title> + <prepared>Lukas Larsson</prepared> + <docno></docno> + <date>2012-07-18</date> + <rev></rev> + <file>part.xml</file> + </header> + + <description> + <p><em>Runtime Tools</em></p> + </description> + + <xi:include href="DTRACE.xml"/> + <xi:include href="SYSTEMTAP.xml"/> +</part> + + + + diff --git a/lib/test_server/src/Makefile b/lib/test_server/src/Makefile index 3106f28d0f..682507ba65 100644 --- a/lib/test_server/src/Makefile +++ b/lib/test_server/src/Makefile @@ -55,7 +55,8 @@ TS_MODULES= \ ts_erl_config \ ts_autoconf_win32 \ ts_install \ - ts_install_cth + ts_install_cth \ + ts_benchmark TARGET_MODULES= $(MODULES:%=$(EBIN)/%) TS_TARGET_MODULES= $(TS_MODULES:%=$(EBIN)/%) diff --git a/lib/test_server/src/ts.erl b/lib/test_server/src/ts.erl index 9241c83fb2..a30f6c65fe 100644 --- a/lib/test_server/src/ts.erl +++ b/lib/test_server/src/ts.erl @@ -28,6 +28,7 @@ clean/0, clean/1, tests/0, tests/1, install/0, install/1, index/0, + bench/0, bench/1, bench/2, benchmarks/0, estone/0, estone/1, cross_cover_analyse/1, compile_testcases/0, compile_testcases/1, @@ -48,12 +49,12 @@ %%% | +------ ts_make %%% | | %%% +-- ts_run -----+ -%%% | ts_filelib -%%% +------ ts_make_erl -%%% | -%%% +------ ts_reports (indirectly) -%%% -%%% +%%% | | ts_filelib +%%% | +------ ts_make_erl +%%% | | +%%% | +------ ts_reports (indirectly) +%%% | +%%% +-- ts_benchmark %%% %%% The modules ts_lib and ts_filelib contains utilities used by %%% the other modules. @@ -80,6 +81,7 @@ %%% of the tests run. %%% ts_lib Miscellanous utility functions, each used by several %%% other modules. +%%% ts_benchmark Supervises otp benchmarks and collects results. %%%---------------------------------------------------------------------- -include_lib("kernel/include/file.hrl"). @@ -127,7 +129,7 @@ help(installed) -> " ts:run(Spec, Mod) - Run a single test suite.\n", " ts:run(Spec, Mod, Case)\n", " - Run a single test case.\n", - " All above run functions can have the additional Options argument\n", + " All above run functions can have an additional Options argument\n", " which is a list of options.\n", "\n", "Run options supported:\n", @@ -157,7 +159,7 @@ help(installed) -> " {ctp | ctpl, Mod, Func}\n", " {ctp | ctpl, Mod, Func, Arity}\n", "\n", - "Support functions\n", + "Support functions:\n", " ts:tests() - Shows all available families of tests.\n", " ts:tests(Spec) - Shows all available test modules in Spec,\n", " i.e. ../Spec_test/*_SUITE.erl\n", @@ -178,6 +180,13 @@ help(installed) -> " - Compile all testcases for usage in a cross ~n" " compile environment." " \n" + "Benchmark functions:\n" + " ts:benchmarks() - Get all available families of benchmarks\n" + " ts:bench() - Runs all benchmarks\n" + " ts:bench(Spec) - Runs all benchmarks in the given spec file.\n" + " The spec file is actually ../*_test/Spec_bench.spec\n\n" + " ts:bench can take the same Options argument as ts:run.\n" + "\n" "Installation (already done):\n" ], show_help([H,?install_help]). @@ -490,6 +499,25 @@ tests(Spec) -> {ok, Cwd} = file:get_cwd(), ts_lib:suites(Cwd, atom_to_list(Spec)). +%% Benchmark related functions + +bench() -> + bench([]). + +bench(Opts) when is_list(Opts) -> + bench(benchmarks(),Opts); +bench(Spec) -> + bench([Spec],[]). + +bench(Spec, Opts) when is_atom(Spec) -> + bench([Spec],Opts); +bench(Specs, Opts) -> + check_and_run(fun(Vars) -> ts_benchmark:run(Specs, Opts, Vars) end). + +benchmarks() -> + ts_benchmark:benchmarks(). + + %% %% estone/0, estone/1 diff --git a/lib/test_server/src/ts_benchmark.erl b/lib/test_server/src/ts_benchmark.erl new file mode 100644 index 0000000000..516d22fd2d --- /dev/null +++ b/lib/test_server/src/ts_benchmark.erl @@ -0,0 +1,91 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2012-2012. All Rights Reserved. +%% +%% The contents of this file are subject to the Erlang Public License, +%% Version 1.1, (the "License"); you may not use this file except in +%% compliance with the License. You should have received a copy of the +%% Erlang Public License along with this software. If not, it can be +%% retrieved online at http://www.erlang.org/. +%% +%% Software distributed under the License is distributed on an "AS IS" +%% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +%% the License for the specific language governing rights and limitations +%% under the License. +%% +%% %CopyrightEnd% +%% +-module(ts_benchmark). + +-include_lib("common_test/include/ct_event.hrl"). +-include_lib("kernel/include/file.hrl"). +-include("ts.hrl"). + +-export([benchmarks/0, + run/3]). + +%% gen_event callbacks +-export([init/1, handle_event/2]). + +benchmarks() -> + {ok, Cwd} = file:get_cwd(), + Benches = filelib:wildcard( + filename:join([Cwd,"..","*_test","*_bench.spec"])), + [begin + Base = filename:basename(N), + list_to_atom(string:substr(Base,1,string:rstr(Base,"_")-1)) + end || N <- Benches]. + +run(Specs, Opts, Vars) -> + {ok, Cwd} = file:get_cwd(), + {{YY,MM,DD},{HH,Mi,SS}} = calendar:local_time(), + BName = lists:concat([YY,"_",MM,"_",DD,"T",HH,"_",Mi,"_",SS]), + BDir = filename:join([Cwd,BName]), + file:make_dir(BDir), + [ts_run:run(atom_to_list(Spec), + [{spec, [atom_to_list(Spec)++"_bench.spec"]}], + [{event_handler, {ts_benchmark, [Spec,BDir]}}|Opts],Vars) + || Spec <- Specs], + file:delete(filename:join(Cwd,"latest_benchmark")), + {ok,D} = file:open(filename:join(Cwd,"latest_benchmark"),[write]), + io:format(D,BDir,[]), + file:close(D). + + +%%%=================================================================== +%%% gen_event callbacks +%%%=================================================================== + +-record(state, { spec, suite, tc, stats_dir}). + +init([Spec,Dir]) -> + {ok, #state{ spec = Spec, stats_dir = Dir }}. + +handle_event(#event{name = tc_start, data = {Suite,Tc}}, State) -> + {ok,State#state{ suite = Suite, tc = Tc}}; +handle_event(#event{name = benchmark_data, data = Data}, State) -> + Spec = proplists:get_value(application, Data, State#state.spec), + Suite = proplists:get_value(suite, Data, State#state.suite), + Tc = proplists:get_value(name, Data, State#state.tc), + Value = proplists:get_value(value, Data), + {ok, D} = file:open(filename:join( + [State#state.stats_dir, + lists:concat([e(Spec),"-",e(Suite),"-", + e(Tc),".ebench"])]), + [append]), + io:format(D, "~p~n",[Value]), + file:close(D), + {ok, State}; +handle_event(_Event, State) -> + {ok, State}. + + +e(Atom) when is_atom(Atom) -> + Atom; +e(Str) when is_list(Str) -> + lists:map(fun($/) -> + $\\; + (C) -> + C + end,Str). diff --git a/lib/test_server/src/ts_lib.erl b/lib/test_server/src/ts_lib.erl index d521d2beda..93d5d78289 100644 --- a/lib/test_server/src/ts_lib.erl +++ b/lib/test_server/src/ts_lib.erl @@ -108,8 +108,16 @@ interesting_logs(Dir) -> specs(Dir) -> Specs = filelib:wildcard(filename:join([filename:dirname(Dir), - "*_test", "*.{dyn,}spec"])), - sort_tests([filename_to_atom(Name) || Name <- Specs]). + "*_test", "*.{dyn,}spec"])), + % Filter away all spec which end with _bench.spec + NoBench = fun(SpecName) -> + case lists:reverse(SpecName) of + "ceps.hcneb_"++_ -> false; + _ -> true + end + end, + + sort_tests([filename_to_atom(Name) || Name <- Specs, NoBench(Name)]). suites(Dir, Spec) -> Glob=filename:join([filename:dirname(Dir), Spec++"_test", diff --git a/make/emd2exml.in b/make/emd2exml.in index 16c38379d9..b677ef8ed4 100644 --- a/make/emd2exml.in +++ b/make/emd2exml.in @@ -266,8 +266,11 @@ parse(#state{code = true, type = blank, line = CB, code_blank = CBs} = S) -> parse(#state{code = true, code_blank = CB, list_lvl = Lvl, - type = {text, TxtLvl}, - line = Line} = S) when TxtLvl > Lvl -> + type = {Type, TxtLvl}, + line = Line} = S) when TxtLvl > Lvl, + (Type == text orelse + Type == uolist orelse + Type == olist) -> Data = code(strip_lvls(Lvl+1, Line)), parse(get_line(put_chars(S#state{code_blank = []}, [strip_code_blank(Lvl+1, CB), Data]))); @@ -994,7 +997,7 @@ resolve_link([_|Cs], start, "", "", "") -> resolve_link(Cs, start, "", "", ""); resolve_link("]:" ++ Rest, key, Yek, "", "") -> resolve_link(Rest, url, Yek, "", ""); -resolve_link([C|Cs], url, Yek, Lru, "") when C == $"; C == $' -> +resolve_link([C|Cs], url, Yek, Lru, "") when C == $"; C == $' -> %" resolve_link(Cs, {title, C}, Yek, Lru, ""); resolve_link([$(|Cs], url, Yek, Lru, "") -> resolve_link(Cs, {title, $)}, Yek, Lru, ""); @@ -1010,9 +1013,21 @@ resolve_link([_|Cs], drop, Yek, Lru, Eltit) -> resolve_link(Cs, drop, Yek, Lru, Eltit); resolve_link([], _, Yek, Lru, Eltit) -> {ws_strip(lists:reverse(Yek)), - ws_strip(lists:reverse(Lru)), + ws_strip(md_strip_n_reverse(Lru)), ws_strip(lists:reverse(Eltit))}. +%% Remove .md at end of references. +md_strip_n_reverse(Lru) -> + md_strip_n_reverse(Lru,[]). +md_strip_n_reverse("\ndm."++Lru,Acc) -> + md_strip_n_reverse(Lru,Acc); +md_strip_n_reverse("#dm."++Lru,Acc) -> + md_strip_n_reverse(Lru,[$#|Acc]); +md_strip_n_reverse([C|T],Acc) -> + md_strip_n_reverse(T,[C|Acc]); +md_strip_n_reverse([], Acc) -> + Acc. + %% %% Misc %% diff --git a/system/doc/installation_guide/Makefile b/system/doc/installation_guide/Makefile index 4636650570..5ad9af4be9 100644 --- a/system/doc/installation_guide/Makefile +++ b/system/doc/installation_guide/Makefile @@ -58,7 +58,8 @@ XML_FILES = \ GENERATED_XML_FILES = \ INSTALL.xml \ INSTALL-CROSS.xml \ - INSTALL-WIN32.xml + INSTALL-WIN32.xml \ + MARKDOWN.xml # ---------------------------------------------------- @@ -73,7 +74,8 @@ REDIRECT_HTML_DIR = $(HTMLDIR)/source REDIRECT_HTML_FILES = \ $(REDIRECT_HTML_DIR)/INSTALL.html \ $(REDIRECT_HTML_DIR)/INSTALL-CROSS.html \ - $(REDIRECT_HTML_DIR)/INSTALL-WIN32.html + $(REDIRECT_HTML_DIR)/INSTALL-WIN32.html \ + $(REDIRECT_HTML_DIR)/MARKDOWN.html # ---------------------------------------------------- # FLAGS @@ -85,7 +87,7 @@ DVIPS_FLAGS += # Targets # ---------------------------------------------------- -%.xml: $(ERL_TOP)/%.md $(ERL_TOP)/make/emd2exml +%.xml: $(ERL_TOP)/HOWTO/%.md $(ERL_TOP)/make/emd2exml $(ERL_TOP)/make/emd2exml $< $@ $(REDIRECT_HTML_DIR)/%.html: Makefile diff --git a/system/doc/installation_guide/part.xml b/system/doc/installation_guide/part.xml index fceacdd8f6..648beb0afd 100644 --- a/system/doc/installation_guide/part.xml +++ b/system/doc/installation_guide/part.xml @@ -36,5 +36,5 @@ <xi:include href="INSTALL.xml"/> <xi:include href="INSTALL-CROSS.xml"/> <xi:include href="INSTALL-WIN32.xml"/> -</part> - + <xi:include href="MARKDOWN.xml"/> +</part>
\ No newline at end of file diff --git a/system/doc/installation_guide/xmlfiles.mk b/system/doc/installation_guide/xmlfiles.mk index dee67b3c70..8ea2b296aa 100644 --- a/system/doc/installation_guide/xmlfiles.mk +++ b/system/doc/installation_guide/xmlfiles.mk @@ -21,4 +21,5 @@ INST_GUIDE_CHAPTER_FILES = \ verification.xml \ INSTALL.xml \ INSTALL-CROSS.xml \ - INSTALL-WIN32.xml + INSTALL-WIN32.xml \ + MARKDOWN.xml diff --git a/xcomp/README.md b/xcomp/README.md index 5f4b36bdca..d08b3160ba 100644..120000 --- a/xcomp/README.md +++ b/xcomp/README.md @@ -1,555 +1 @@ -Cross Compiling Erlang/OTP -========================== - -Introduction ------------- - -This document describes how to cross compile Erlang/OTP-%OTP-REL%. Note that -the support for cross compiling Erlang/OTP should be considered as -experimental. As far as we know, the %OTP-REL% release should cross compile -fine, but since we currently have a very limited set of cross compilation -environments to test with we cannot be sure. The cross compilation support -will remain in an experimental state until we get a lot more cross compilation -environments to test with. - -You are advised to read the whole document before attempting to cross -compile Erlang/OTP. However, before reading this document, you should read -the [$ERL_TOP/INSTALL.md][] document which describes building and installing -Erlang/OTP in general. `$ERL_TOP` is the top directory in the source tree. - -### otp\_build Versus configure/make ### - -Building Erlang/OTP can be done either by using the `$ERL_TOP/otp_build` -script, or by invoking `$ERL_TOP/configure` and `make` directly. Building using -`otp_build` is easier since it involves fewer steps, but the `otp_build` build -procedure is not as flexible as the `configure`/`make` build procedure. Note -that `otp_build configure` will produce a default configuration that differs -from what `configure` will produce by default. For example, currently -`--disable-dynamic-ssl-lib` is added to the `configure` command line arguments -unless `--enable-dynamic-ssl-lib` has been explicitly passed. The binary -releases that we deliver are built using `otp_build`. The defaults used by -`otp_build configure` may change at any time without prior notice. - -### Cross Configuration ### - -The `$ERL_TOP/xcomp/erl-xcomp.conf.template` file contains all available cross -configuration variables and can be used as a template when creating a cross -compilation configuration. All [cross configuration variables][] are also -listed at the end of this document. For examples of working cross -configurations see the `$ERL_TOP/xcomp/erl-xcomp-TileraMDE2.0-tilepro.conf` -file and the `$ERL_TOP/xcomp/erl-xcomp-x86_64-saf-linux-gnu.conf` file. If the -default behavior of a variable is satisfactory, the variable does not need to -be set. However, the `configure` script will issue a warning when a default -value is used. When a variable has been set, no warning will be issued. - -A cross configuration file can be passed to `otp_build configure` using the -`--xcomp-conf` command line argument. Note that `configure` does not accept -this command line argument. When using the `configure` script directly, pass -the configuration variables as arguments to `configure` using a -`<VARIABLE>=<VALUE>` syntax. Variables can also be passed as environment -variables to `configure`. However, if you pass the configuration in the -environment, make sure to unset all of these environment variables before -invoking `make`; otherwise, the environment variables might set make variables -in some applications, or parts of some applications, and you may end up with -an erroneously configured build. - -### What can be Cross Compiled? ### - -All Erlang/OTP applications except the `wx` application can be cross compiled. -The build of the `wx` driver will currently be automatically disabled when -cross compiling. - -### Compatibility ### - -The build system, including cross compilation configuration variables used, -may be subject to non backward compatible changes without prior notice. -Current cross build system has been tested when cross compiling some Linux/GNU -systems, but has only been partly tested for more esoteric platforms. The -VxWorks example file is highly dependent on our environment and is here more -or less only for internal use. - -### Patches ### - -Please submit any patches for cross compiling in a way consistent with this -system. All input is welcome as we have a very limited set of cross compiling -environments to test with. If a new configuration variable is needed, add it -to `$ERL_TOP/xcomp/erl-xcomp.conf.template`, and use it in `configure.in`. -Other files that might need to be updated are: - -- `$ERL_TOP/xcomp/erl-xcomp-vars.sh` -- `$ERL_TOP/erl-build-tool-vars.sh` -- `$ERL_TOP/erts/aclocal.m4` -- `$ERL_TOP/xcomp/README.md` -- `$ERL_TOP/xcomp/erl-xcomp-*.conf` - -Note that this might be an incomplete list of files that need to be updated. - -General information on how to submit patches can be found at: - <http://wiki.github.com/erlang/otp/submitting-patches> - -Build and Install Procedure ---------------------------- - -If you are building in Git, you want to read the [Building in Git][] section -of [$ERL_TOP/INSTALL.md][] before proceeding. - -We will first go through the `configure`/`make` build procedure which people -probably are most familiar with. - -### Building With configure/make Directly ### - - (1) - -Change directory into the top directory of the Erlang/OTP source tree. - - $ cd $ERL_TOP - -In order to compile Erlang code, a small Erlang bootstrap system has to be -built, or an Erlang/OTP system of the same release as the one being built -has to be provided in the `$PATH`. The Erlang/OTP for the target system will -be built using this Erlang system, together with the cross compilation tools -provided. - -If you want to build the documentation out of the same source tree as you are -cross compiling in, you currently need a full Erlang/OTP system of the same -release as the one being built for the build machine. If this is the case, -build and install one for the build machine (or use one already built) and add -it to the `$PATH` before cross building, and building the documentation. See -the [How to Build the Documentation][] section in the [$ERL_TOP/INSTALL.md][] -document for information on how to build the documentation. - -If you want to build using a compatible Erlang/OTP system in the `$PATH`, -jump to (3). - -#### Building a Bootstrap System #### - - (2) - - $ ./configure --enable-bootstrap-only - $ make - -The `--enable-bootstrap-only` argument to `configure` isn't strictly necessary, -but will speed things up. It will only run `configure` in applications -necessary for the bootstrap, and will disable a lot of things not needed by -the bootstrap system. If you run `configure` without `--enable-boostrap-only` -you also have to run make as `make bootstrap`; otherwise, the whole system will -be built. - -#### Cross Building the System #### - - (3) - - $ ./configure --host=<HOST> --build=<BUILD> [Other Config Args] - $ make - -`<HOST>` is the host/target system that you build for. It does not have to be -a full `CPU-VENDOR-OS` triplet, but can be. The full `CPU-VENDOR-OS` triplet -will be created by executing `$ERL_TOP/erts/autoconf/config.sub <HOST>`. If -`config.sub` fails, you need to be more specific. - -`<BUILD>` should equal the `CPU-VENDOR-OS` triplet of the system that you -build on. If you execute `$ERL_TOP/erts/autoconf/config.guess`, it will in -most cases print the triplet you want to use for this. - -Pass the cross compilation variables as command line arguments to `configure` -using a `<VARIABLE>=<VALUE>` syntax. - -> *NOTE*: You can *not* pass a configuration file using the `--xcomp-conf` -> argument when you invoke `configure` directly. The `--xcomp-conf` argument -> can only be passed to `otp_build configure`. - -`make` will verify that the Erlang/OTP system used when building is of the -same release as the system being built, and will fail if this is not the case. -It is possible, however not recommended, to force the cross compilation even -though the wrong Erlang/OTP system is used. This by invoking `make` like this: -`make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes`. - -> *WARNING*: Invoking `make ERL_XCOMP_FORCE_DIFFERENT_OTP=yes` might fail, -> silently produce suboptimal code, or silently produce erroneous code. - -#### Installing #### - -You can either install using the installation paths determined by `configure` -(4), or install manually using (5). - -##### Installing Using Paths Determined by configure ##### - - (4) - - $ make install DESTDIR=<TEMPORARY_PREFIX> - -`make install` will install at a location specified when doing `configure`. -`configure` arguments specifying where the installation should reside are for -example: `--prefix`, `--exec-prefix`, `--libdir`, `--bindir`, etc. By default -it will install under `/usr/local`. You typically do not want to install your -cross build under `/usr/local` on your build machine. Using [DESTDIR][] -will cause the installation paths to be prefixed by `$DESTDIR`. This makes it -possible to install and package the installation on the build machine without -having to place the installation in the same directory on the build machine as -it should be executed from on the target machine. - -When `make install` has finished, change directory into `$DESTDIR`, package -the system, move it to the target machine, and unpack it. Note that the -installation will only be working on the target machine at the location -determined by `configure`. - -##### Installing Manually ##### - - (5) - - $ make release RELEASE_ROOT=<RELEASE_DIR> - -`make release` will copy what you have built for the target machine to -`<RELEASE_DIR>`. The `Install` script will not be run. The content of -`<RELEASE_DIR>` is what by default ends up in `/usr/local/lib/erlang`. - -The `Install` script used when installing Erlang/OTP requires common Unix -tools such as `sed` to be present in your `$PATH`. If your target system -does not have such tools, you need to run the `Install` script on your -build machine before packaging Erlang/OTP. The `Install` script should -currently be invoked as follows in the directory where it resides -(the top directory): - - $ ./Install [-cross] [-minimal|-sasl] <ERL_ROOT> - -where: - -* `-minimal` Creates an installation that starts up a minimal amount - of applications, i.e., only `kernel` and `stdlib` are started. The - minimal system is normally enough, and is what `make install` uses. -* `-sasl` Creates an installation that also starts up the `sasl` - application. -* `-cross` For cross compilation. Informs the install script that it - is run on the build machine. -* `<ERL_ROOT>` - The absolute path to the Erlang installation to use - at run time. This is often the same as the current working directory, - but does not have to be. It can follow any other path through the file - system to the same directory. - -If neither `-minimal`, nor `-sasl` is passed as argument you will be -prompted. - -You can now either do: - - (6) - -* Decide where the installation should be located on the target machine, - run the `Install` script on the build machine, and package the installed - installation. The installation just need to be unpacked at the right - location on the target machine: - - $ cd <RELEASE_DIR> - $ ./Install -cross [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> - -or: - - (7) - -* Package the installation in `<RELEASE_DIR>`, place it wherever you want - on your target machine, and run the `Install` script on your target - machine: - - $ cd <ABSOLUTE_INSTALL_DIR_ON_TARGET> - $ ./Install [-minimal|-sasl] <ABSOLUTE_INSTALL_DIR_ON_TARGET> - -### Building With the otp\_build Script ### - - (8) - - $ cd $ERL_TOP - - (9) - - $ ./otp_build configure --xcomp-conf=<FILE> [Other Config Args] - -alternatively: - - $ ./otp_build configure --host=<HOST> --build=<BUILD> [Other Config Args] - -If you have your cross compilation configuration in a file, pass it using the -`--xcomp-conf=<FILE>` command line argument. If not, pass `--host=<HOST>`, -`--build=<BUILD>`, and the configuration variables using a `<VARIABLE>=<VALUE>` -syntax on the command line (same as in (3)). Note that `<HOST>` and `<BUILD>` -have to be passed one way or the other; either by using `erl_xcomp_host=<HOST>` -and `erl_xcomp_build=<BUILD>` in the configuration file, or by using the -`--host=<HOST>`, and `--build=<BUILD>` command line arguments. - -`otp_build configure` will configure both for the boostrap system on the -build machine and the cross host system. - - (10) - - $ ./otp_build boot -a - -`otp_build boot -a` will first build a bootstrap system for the build machine -and then do the cross build of the system. - - (11) - - $ ./otp_build release -a <RELEASE_DIR> - -`otp_build release -a` will do the same as (5), and you will after this have -to do a manual install either by doing (6), or (7). - -Testing the cross compiled system --------------------------------------- -Some of the tests that come with erlang use native code to test. This means -that when cross compiling erlang you also have to cross compile test suites -in order to run tests on the target host. To do this you first have to release -the tests as usual. - - $ make release_tests - -or - - $ ./otp_build tests - -The tests will be released into `$ERL_TOP/release/tests`. After releasing the -tests you have to install the tests on the build machine. You supply the same -xcomp file as to `./otp_build` in (9). - - $ cd $ERL_TOP/release/tests/test_server/ - $ $ERL_TOP/bootstrap/bin/erl -eval 'ts:install([{xcomp,"<FILE>"}])' -s ts compile_testcases -s init stop - -You should get a lot of printouts as the testcases are compiled. Once done you -should copy the entire `$ERL_TOP/release/tests` folder to the cross host system. - -Then go to the cross host system and setup the erlang installed in (4) or (5) -to be in your `$PATH`. Then go to what previously was -`$ERL_TOP/release/tests/test_server` and issue the following command. - - $ erl -s ts install -s ts run all_tests -s init stop - -The configure should be skipped and all tests should hopefully pass. For more -details about how to use ts run `erl -s ts help -s init stop` - -Currently Used Configuration Variables --------------------------------------- - -Note that you cannot define arbitrary variables in a cross compilation -configuration file. Only the ones listed below will be guaranteed to be -visible throughout the whole execution of all `configure` scripts. Other -variables needs to be defined as arguments to `configure` or exported in -the environment. - -### Variables for otp\_build Only ### - -Variables in this section are only used, when configuring Erlang/OTP for -cross compilation using `$ERL_TOP/otp_build configure`. - -> *NOTE*: These variables currently have *no* effect if you configure using -> the `configure` script directly. - -* `erl_xcomp_build` - The build system used. This value will be passed as - `--build=$erl_xcomp_build` argument to the `configure` script. It does - not have to be a full `CPU-VENDOR-OS` triplet, but can be. The full - `CPU-VENDOR-OS` triplet will be created by - `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_build`. If set to `guess`, - the build system will be guessed using - `$ERL_TOP/erts/autoconf/config.guess`. - -* `erl_xcomp_host` - Cross host/target system to build for. This value will - be passed as `--host=$erl_xcomp_host` argument to the `configure` script. - It does not have to be a full `CPU-VENDOR-OS` triplet, but can be. The - full `CPU-VENDOR-OS` triplet will be created by - `$ERL_TOP/erts/autoconf/config.sub $erl_xcomp_host`. - -* `erl_xcomp_configure_flags` - Extra configure flags to pass to the - `configure` script. - -### Cross Compiler and Other Tools ### - -If the cross compilation tools are prefixed by `<HOST>-` you probably do -not need to set these variables (where `<HOST>` is what has been passed as -`--host=<HOST>` argument to `configure`). - -All variables in this section can also be used when native compiling. - -* `CC` - C compiler. - -* `CFLAGS` - C compiler flags. - -* `STATIC_CFLAGS` - Static C compiler flags. - -* `CFLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library - search path for the shared libraries. Note that this actually is a - linker flag, but it needs to be passed via the compiler. - -* `CPP` - C pre-processor. - -* `CPPFLAGS` - C pre-processor flags. - -* `CXX` - C++ compiler. - -* `CXXFLAGS` - C++ compiler flags. - -* `LD` - Linker. - -* `LDFLAGS` - Linker flags. - -* `LIBS` - Libraries. - -#### Dynamic Erlang Driver Linking #### - -> *NOTE*: Either set all or none of the `DED_LD*` variables. - -* `DED_LD` - Linker for Dynamically loaded Erlang Drivers. - -* `DED_LDFLAGS` - Linker flags to use with `DED_LD`. - -* `DED_LD_FLAG_RUNTIME_LIBRARY_PATH` - This flag should set runtime library - search path for shared libraries when linking with `DED_LD`. - -#### Large File Support #### - -> *NOTE*: Either set all or none of the `LFS_*` variables. - -* `LFS_CFLAGS` - Large file support C compiler flags. - -* `LFS_LDFLAGS` - Large file support linker flags. - -* `LFS_LIBS` - Large file support libraries. - -#### Other Tools #### - -* `RANLIB` - `ranlib` archive index tool. - -* `AR` - `ar` archiving tool. - -* `GETCONF` - `getconf` system configuration inspection tool. `getconf` is - currently used for finding out large file support flags to use, and - on Linux systems for finding out if we have an NPTL thread library or - not. - -### Cross System Root Locations ### - -* `erl_xcomp_sysroot` - The absolute path to the system root of the cross - compilation environment. Currently, the `crypto`, `odbc`, `ssh` and - `ssl` applications need the system root. These applications will be - skipped if the system root has not been set. The system root might be - needed for other things too. If this is the case and the system root - has not been set, `configure` will fail and request you to set it. - -* `erl_xcomp_isysroot` - The absolute path to the system root for includes - of the cross compilation environment. If not set, this value defaults - to `$erl_xcomp_sysroot`, i.e., only set this value if the include system - root path is not the same as the system root path. - -### Optional Feature, and Bug Tests ### - -These tests cannot (always) be done automatically when cross compiling. You -usually do not need to set these variables. - -> *WARNING*: Setting these variables wrong may cause hard to detect -> runtime errors. If you need to change these values, *really* make sure -> that the values are correct. - -> *NOTE*: Some of these values will override results of tests performed -> by `configure`, and some will not be used until `configure` is sure that -> it cannot figure the result out. - -The `configure` script will issue a warning when a default value is used. -When a variable has been set, no warning will be issued. - -* `erl_xcomp_after_morecore_hook` - `yes|no`. Defaults to `no`. If `yes`, - the target system must have a working `__after_morecore_hook` that can be - used for tracking used `malloc()` implementations core memory usage. - This is currently only used by unsupported features. - -* `erl_xcomp_bigendian` - `yes|no`. No default. If `yes`, the target system - must be big endian. If `no`, little endian. This can often be - automatically detected, but not always. If not automatically detected, - `configure` will fail unless this variable is set. Since no default - value is used, `configure` will try to figure this out automatically. - -* `erl_xcomp_clock_gettime_cpu_time` - `yes|no`. Defaults to `no`. If `yes`, - the target system must have a working `clock_gettime()` implementation - that can be used for retrieving process CPU time. - -* `erl_xcomp_getaddrinfo` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have a working `getaddrinfo()` implementation that can - handle both IPv4 and IPv6. - -* `erl_xcomp_gethrvtime_procfs_ioctl` - `yes|no`. Defaults to `no`. If `yes`, - the target system must have a working `gethrvtime()` implementation and - is used with procfs `ioctl()`. - -* `erl_xcomp_dlsym_brk_wrappers` - `yes|no`. Defaults to `no`. If `yes`, the - target system must have a working `dlsym(RTLD_NEXT, <S>)` implementation - that can be used on `brk` and `sbrk` symbols used by the `malloc()` - implementation in use, and by this track the `malloc()` implementations - core memory usage. This is currently only used by unsupported features. - -* `erl_xcomp_kqueue` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have a working `kqueue()` implementation that returns a file - descriptor which can be used by `poll()` and/or `select()`. If `no` and - the target system has not got `epoll()` or `/dev/poll`, the kernel-poll - feature will be disabled. - -* `erl_xcomp_linux_clock_gettime_correction` - `yes|no`. Defaults to `yes` on - Linux; otherwise, `no`. If `yes`, `clock_gettime(CLOCK_MONOTONIC, _)` on - the target system must work. This variable is recommended to be set to - `no` on Linux systems with kernel versions less than 2.6. - -* `erl_xcomp_linux_nptl` - `yes|no`. Defaults to `yes` on Linux; otherwise, - `no`. If `yes`, the target system must have NPTL (Native POSIX Thread - Library). Older Linux systems have LinuxThreads instead of NPTL (Linux - kernel versions typically less than 2.6). - -* `erl_xcomp_linux_usable_sigaltstack` - `yes|no`. Defaults to `yes` on Linux; - otherwise, `no`. If `yes`, `sigaltstack()` must be usable on the target - system. `sigaltstack()` on Linux kernel versions less than 2.4 are - broken. - -* `erl_xcomp_linux_usable_sigusrx` - `yes|no`. Defaults to `yes`. If `yes`, - the `SIGUSR1` and `SIGUSR2` signals must be usable by the ERTS. Old - LinuxThreads thread libraries (Linux kernel versions typically less than - 2.2) used these signals and made them unusable by the ERTS. - -* `erl_xcomp_poll` - `yes|no`. Defaults to `no` on Darwin/MacOSX; otherwise, - `yes`. If `yes`, the target system must have a working `poll()` - implementation that also can handle devices. If `no`, `select()` will be - used instead of `poll()`. - -* `erl_xcomp_putenv_copy` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have a `putenv()` implementation that stores a copy of the - key/value pair. - -* `erl_xcomp_reliable_fpe` - `yes|no`. Defaults to `no`. If `yes`, the target - system must have reliable floating point exceptions. - -Copyright and License ---------------------- - -%CopyrightBegin% - -Copyright Ericsson AB 2009-2010. All Rights Reserved. - -The contents of this file are subject to the Erlang Public License, -Version 1.1, (the "License"); you may not use this file except in -compliance with the License. You should have received a copy of the -Erlang Public License along with this software. If not, it can be -retrieved online at http://www.erlang.org/. - -Software distributed under the License is distributed on an "AS IS" -basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See -the License for the specific language governing rights and limitations -under the License. - -%CopyrightEnd% - -Modifying This Document ------------------------ - -Before modifying this document you need to have a look at the -`$ERL_TOP/README.md.txt` document. - - - - [$ERL_TOP/INSTALL.md]: INSTALL - [Building in Git]: INSTALL#How-to-Build-and-Install-ErlangOTP_Building-in-Git - [How to Build the Documentation]: INSTALL#The-ErlangOTP-Documentation_How-to-Build-the-Documentation - [cross configuration variables]: #Currently-Used-Configuration-Variables - [DESTDIR]: http://www.gnu.org/prep/standards/html_node/DESTDIR.html - - [?TOC]: true +../HOWTO/INSTALL-CROSS.md
\ No newline at end of file |