aboutsummaryrefslogtreecommitdiffstats
path: root/HOWTO
diff options
context:
space:
mode:
Diffstat (limited to 'HOWTO')
-rw-r--r--HOWTO/INSTALL-WIN32.md21
-rw-r--r--HOWTO/INSTALL.md45
-rw-r--r--HOWTO/OTP-PATCH-APPLY.md144
3 files changed, 180 insertions, 30 deletions
diff --git a/HOWTO/INSTALL-WIN32.md b/HOWTO/INSTALL-WIN32.md
index 0387572dd3..3039a5efea 100644
--- a/HOWTO/INSTALL-WIN32.md
+++ b/HOWTO/INSTALL-WIN32.md
@@ -639,30 +639,25 @@ OpenSSL. Well' here's the list:
The installation locations chosen are where configure will look
for OpenSSL, so try to keep them as is.
-* Building with wxWidgets. Download wxWidgets-2.8.9 or higher patch
- release (2.9.\* is a developer release which currently does not work
- with wxErlang).
+* Building with wxWidgets. Download wxWidgets-3.0.2 or higher patch
+ release.
Install or unpack it to `DRIVE:/PATH/cygwin/opt/local/pgm`.
- edit: `C:\cygwin\opt\local\pgm\wxMSW-2.8.11\include\wx\msw\setup.h`
- enable `wxUSE_GLCANVAS`, `wxUSE_POSTSCRIPT` and `wxUSE_GRAPHICS_CONTEXT`
+ edit: `C:\cygwin\opt\local\pgm\wxMSW-3.0.2\include\wx\msw\setup.h`
+ enable `wxUSE_POSTSCRIPT`
build: From a command prompt with the VC tools available (See the
instructions for OpenSSL build above for help on starting the
proper command prompt in RELEASE mode):
- C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\build\msw
- C:\...\> nmake BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc
- C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\contrib\build\stc
- C:\...\> nmake BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc
+ C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-3.0.2\build\msw
+ C:\...\> nmake BUILD=release SHARED=0 DIR_SUFFIX_CPU= -f makefile.vc
Or - if building a 64bit version:
- C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\build\msw
- C:\...\> nmake TARGET_CPU=amd64 BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc
- C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-2.8.11\contrib\build\stc
- C:\...\> nmake TARGET_CPU=amd64 BUILD=release SHARED=0 UNICODE=1 USE_OPENGL=1 USE_GDIPLUS=1 DIR_SUFFIX_CPU= -f makefile.vc
+ C:\...\> cd C:\cygwin\opt\local\pgm\wxMSW-3.0.2\build\msw
+ C:\...\> nmake TARGET_CPU=amd64 BUILD=release SHARED=0 DIR_SUFFIX_CPU= -f makefile.vc
* The Erlang source distribution (from <http://www.erlang.org/download.html>).
The same as for Unix platforms. Preferably use tar from within Cygwin to
diff --git a/HOWTO/INSTALL.md b/HOWTO/INSTALL.md
index 53b1b8cd8a..7efea77d4c 100644
--- a/HOWTO/INSTALL.md
+++ b/HOWTO/INSTALL.md
@@ -417,22 +417,33 @@ important when building Erlang/OTP. By default the VM will refuse to build
if native atomic memory operations are not available.
Erlang/OTP itself provides implementations of native atomic memory operations
-that can be used when compiling with a `gcc` compatible compiler on 32-bit
-and 64-bit x86, 32-bit and 64-bit SPARC V9, and 32-bit PowerPC. When compiling
-with a `gcc` compatible compiler on other architectures, the VM may be able to
-make use of native atomic operations using the `__sync_*` primitives, but this
-should only be used as a last resort since this wont give you optimal
-performance. When compiling on Windows using a MicroSoft Visual C++ compiler
-native atomic memory operations are provided by Windows APIs.
-
-You are recommended to use the native atomic implementation provided by
-Erlang/OTP, or the API provided by Windows. If these do not provide native
-atomics on your platform, you are recommended to build and install
-[libatomic_ops][] before building Erlang/OTP. The `libatomic_ops` library
-provides native atomic memory operations for a variety of platforms and
-compilers. When building Erlang/OTP you need to inform the build system of
-where the `libatomic_ops` library is installed using the
-`--with-libatomic_ops=PATH` configure switch.
+that can be used when compiling with a `gcc` compatible compiler for 32/64-bit
+x86, 32/64-bit SPARC V9, 32-bit PowerPC, or 32-bit Tile. When compiling with
+a `gcc` compatible compiler for other architectures, the VM may be able to make
+use of native atomic operations using the `__atomic_*` builtins (may be
+available when using a `gcc` of at least version 4.7) and/or using the
+`__sync_*` builtins (may be available when using a `gcc` of at least version
+4.1). If only the `gcc`'s `__sync_*` builtins are available, the performance
+will suffer. Such a configuration should only be used as a last resort. When
+compiling on Windows using a MicroSoft Visual C++ compiler native atomic
+memory operations are provided by Windows APIs.
+
+Native atomic implementation in the order preferred:
+1. The implementation provided by Erlang/OTP.
+2. The API provided by Windows.
+3. The implementation based on the `gcc` `__atomic_*` builtins.
+4. If none of the above are available for your architecture/compiler, you
+ are recommended to build and install [libatomic_ops][] before building
+ Erlang/OTP. The `libatomic_ops` library provides native atomic memory
+ operations for a variety of architectures and compilers. When building
+ Erlang/OTP you need to inform the build system of where the
+ `libatomic_ops` library is installed using the
+ `--with-libatomic_ops=PATH` `configure` switch.
+5. As a last resort, the implementation solely based on the `gcc`
+ `__sync_*` builtins. This will however cause lots of expensive and
+ unnecessary memory barrier instructions to be issued. That is,
+ performance will suffer. The `configure` script will warn at the end
+ of its execution if it cannot find any other alternative than this.
### Building ###
@@ -849,7 +860,7 @@ Copyright and License
%CopyrightBegin%
-Copyright Ericsson AB 1998-2014. All Rights Reserved.
+Copyright Ericsson AB 1998-2015. 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
diff --git a/HOWTO/OTP-PATCH-APPLY.md b/HOWTO/OTP-PATCH-APPLY.md
new file mode 100644
index 0000000000..2aa31629ef
--- /dev/null
+++ b/HOWTO/OTP-PATCH-APPLY.md
@@ -0,0 +1,144 @@
+Patching OTP Applications
+=========================
+
+Introduction
+------------
+
+This document describes the process of patching an existing OTP
+installation with one or more Erlang/OTP applications of newer versions
+than already installed. The tool `otp_patch_apply` is available for this
+specific purpose. It resides in the top directory of the Erlang/OTP
+source tree.
+
+The `otp_patch_apply` tool utilizes the [runtime_dependencies][] tag in
+the [application resource file][]. This information is used to determine
+if the patch can be installed in the given Erlang/OTP installation
+directory.
+
+Read more about the [version handling][] introduced in Erlang/OTP release
+17, which also describes how to determine if an installation includes one
+or more patched applications.
+
+If you want to apply patches of multiple OTP applications that resides
+in different OTP versions, you have to apply these patches in multiple
+steps. It is only possible to apply multiple OTP applications from the
+same OTP version at once.
+
+Prerequisites
+-------------
+
+It's assumed that the reader is familiar with
+[building and installing Erlang/OTP][]. To be able to patch an
+application, the following must exist:
+
+* An Erlang/OTP installation.
+
+* An Erlang/OTP source tree containing the updated applications that
+ you want to patch into the existing Erlang/OTP installation.
+
+Using otp\_patch\_apply
+-----------------------
+
+> *WARNING*: Patching applications is a one-way process.
+> Create a backup of your OTP installation directory before
+> proceeding.
+
+First of all, build the OTP source tree at `$ERL_TOP` containing
+the updated applications.
+
+> *NOTE*: Before applying a patch you need to do a *full* build
+> of OTP in the source directory.
+
+If you are building in `git` you first need to generate the
+`configure` scripts:
+
+ $ ./otp_build autoconf
+
+Configure and build all applications in OTP:
+
+ $ configure
+ $ make
+
+or
+
+ $ ./otp_build configure
+ $ ./otp_build boot -a
+
+If you have installed documentation in the OTP installation, also
+build the documentation:
+
+ $ make docs
+
+After the successful build it's time to patch. The source tree directory,
+the directory of the installation and the applications to patch are given
+as arguments to `otp_patch_apply`. The dependencies of each application
+are validated against the applications in the installation and the other
+applications given as arguments. If a dependency error is detected, the
+script will be aborted.
+
+The `otp_patch_apply` syntax:
+
+ $ otp_patch_apply -s <Dir> -i <Dir> [-l <Dir>] [-c] [-f] [-h] \
+ [-n] [-v] <App1> [... <AppN>]
+
+ -s <Dir> -- OTP source directory that contains build results.
+ -i <Dir> -- OTP installation directory to patch.
+ -l <Dir> -- Alternative OTP source library directory path(s)
+ containing build results of OTP applications.
+ Multiple paths should be colon separated.
+ -c -- Cleanup (remove) old versions of applications
+ patched in the installation.
+ -f -- Force patch of application(s) even though
+ dependencies are not fulfilled (should only be
+ considered in a test environment).
+ -h -- Print help then exit.
+ -n -- Do not install documentation.
+ -v -- Print version then exit.
+ <AppX> -- Application to patch.
+
+ Environment Variable:
+ ERL_LIBS -- Alternative OTP source library directory path(s)
+ containing build results of OTP applications.
+ Multiple paths should be colon separated.
+
+> *NOTE*: The complete build environment is required while running
+> `otp_patch_apply`.
+
+> *NOTE*: All source directories identified by `-s` and `-l` should
+> contain build results of OTP applications.
+
+For example, if the user wants to install patched versions of `mnesia`
+and `ssl` built in `/home/me/git/otp` into the OTP installation
+located in `/opt/erlang/my_otp` type
+
+ $ otp_patch_apply -s /home/me/git/otp -i /opt/erlang/my_otp \
+ mnesia ssl
+
+> *NOTE*: If the list of applications contains core applications,
+> i.e `erts`, `kernel`, `stdlib` or `sasl`, the `Install` script in
+> the patched Erlang/OTP installation must be rerun.
+
+The patched applications are appended to the list of installed
+applications. Take a look at
+`<InstallDir>/releases/OTP-REL/installed_application_versions`.
+
+Sanity check
+------------
+
+The application dependencies can be checked using the Erlang shell.
+Application dependencies are verified among installed applications by
+`otp_patch_apply`, but these are not necessarily those actually loaded.
+By calling `system_information:sanity_check()` one can validate
+dependencies among applications actually loaded.
+
+ 1> system_information:sanity_check().
+ ok
+
+Please take a look at the reference of [sanity_check()][] for more
+information.
+
+[application resource file]: kernel:app
+[runtime_dependencies]: kernel:app#runtime_dependencies
+[building and installing Erlang/OTP]: INSTALL.md
+[version handling]: ../system_principles/versions
+[sanity_check()]: runtime_tools:system_information#sanity_check-0