diff options
Diffstat (limited to 'HOWTO')
| -rw-r--r-- | HOWTO/INSTALL-CROSS.md | 21 | ||||
| -rw-r--r-- | HOWTO/INSTALL-WIN32.md | 42 | ||||
| -rw-r--r-- | HOWTO/INSTALL.md | 79 | ||||
| -rw-r--r-- | HOWTO/MARKDOWN.md | 21 | ||||
| -rw-r--r-- | HOWTO/OTP-PATCH-APPLY.md | 144 |
5 files changed, 253 insertions, 54 deletions
diff --git a/HOWTO/INSTALL-CROSS.md b/HOWTO/INSTALL-CROSS.md index 7f852860c9..224f238fd0 100644 --- a/HOWTO/INSTALL-CROSS.md +++ b/HOWTO/INSTALL-CROSS.md @@ -550,16 +550,17 @@ Copyright and License Copyright Ericsson AB 2009-2014. 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. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. %CopyrightEnd% diff --git a/HOWTO/INSTALL-WIN32.md b/HOWTO/INSTALL-WIN32.md index 0387572dd3..79d89551c0 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 @@ -1020,16 +1015,17 @@ Copyright and License Copyright Ericsson AB 2003-2014. 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. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. %CopyrightEnd% diff --git a/HOWTO/INSTALL.md b/HOWTO/INSTALL.md index 7a7e63164c..51e8648a4a 100644 --- a/HOWTO/INSTALL.md +++ b/HOWTO/INSTALL.md @@ -210,6 +210,14 @@ the `$PATH`. $ export PATH=$ERL_TOP/bin:$PATH # Assuming bash/sh +For the FOP print formatter, two steps must be taken: + +* Adding the location of your installation of `fop` in `$FOP_HOME`. + + $ export FOP_HOME=/path/to/fop/dir # Assuming bash/sh + +* Adding the `fop` script (in `$FOP_HOME`) to your `$PATH`, either by adding `$FOP_HOME` to `$PATH`, or by copying the `fop` script to a directory already in your `$PATH`. + Build the documentation. $ make docs @@ -400,6 +408,18 @@ Some of the available `configure` options are: no automatic dependency handling between applications. If you disable an application that another application depends on, you also have to disable the dependant application. +* `--enable-gettimeofday-as-os-system-time` - Force usage of `gettimeofday()` for + OS system time. +* `--enable-prefer-elapsed-monotonic-time-during-suspend` - Prefer an OS monotonic + time source with elapsed time during suspend. +* `--disable-prefer-elapsed-monotonic-time-during-suspend` - Do not prefer an OS + monotonic time source with elapsed time during suspend. +* `--with-clock-resolution=high|low` - Try to find clock sources for OS system + time, and OS monotonic time with higher or lower resolution than chosen by + default. Note that both alternatives may have a negative impact on the performance + and scalability compared to the default clock sources chosen. +* `--disable-saved-compile-time` - Disable saving of compile date and time + in the emulator binary. * `--enable-dirty-schedulers` - Enable the **experimental** dirty schedulers functionality. Note that the dirty schedulers functionality is experimental, and **not supported**. This functionality **will** be subject to backward @@ -409,6 +429,41 @@ Some of the available `configure` options are: If you or your system has special requirements please read the `Makefile` for additional configuration information. +#### Atomic Memory Operations and the VM #### + +The VM with SMP support makes quite a heavy use of atomic memory operations. +An implementation providing native atomic memory operations is therefore very +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 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 ### @@ -461,7 +516,7 @@ If you have Xcode 4.3, or later, you will also need to download If you want to build the `wx` application, you will need to get wxWidgets-3.0 (`wxWidgets-3.0.0.tar.bz2` from <http://sourceforge.net/projects/wxwindows/files/3.0.0/>) or get it from github with bug fixes: - $ git clone --branch WX_3_0_branch [email protected]:wxWidgets/wxWidgets.git + $ git clone --branch WX_3_0_BRANCH [email protected]:wxWidgets/wxWidgets.git Be aware that the wxWidgets-3.0 is a new release of wxWidgets, it is not as mature as the old releases and the OS X port still lags behind the other ports. @@ -825,18 +880,19 @@ 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 -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/. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 -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. +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. %CopyrightEnd% @@ -862,3 +918,4 @@ under the License. [Optional Utilities]: #Optional-Utilities [Building on a Mac]: #Advanced-configuration-and-build-of-ErlangOTP_Building_OS-X-Darwin [Building with wxErlang]: #Advanced-configuration-and-build-of-ErlangOTP_Building_Building-with-wxErlang + [libatomic_ops]: https://github.com/ivmai/libatomic_ops/ diff --git a/HOWTO/MARKDOWN.md b/HOWTO/MARKDOWN.md index 8e8a5c02cf..2df0460dab 100644 --- a/HOWTO/MARKDOWN.md +++ b/HOWTO/MARKDOWN.md @@ -246,16 +246,17 @@ Copyright and License Copyright Ericsson AB 2010-2013. 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. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. %CopyrightEnd% 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 |