Skip to content

Commit f5347b9

Browse files
tresftresf
committed
Update documentation
1 parent a131add commit f5347b9

File tree

1 file changed

+107
-99
lines changed

1 file changed

+107
-99
lines changed

‎www/WindowsDevelopmentEnvironment.md

+107-99
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,130 @@
11
Setting up a Windows Development Environment
22
============================================
33

4-
Java
5-
----
4+
This builds the library based on the Visual C++ compiler, but can be [adjusted to work without](#mingw-only) if needed.
65

7-
For a 32-bit build, set `JAVA_HOME` to a 32-bit JDK, eg. `C:\Program Files (x86)\java\jdk1.6.0_24`.
8-
For a 64-bit build, set `JAVA_HOME` to a 64-bit JDK, eg. `C:\Program Files\java\jdk1.6.0_24`.
6+
### Background
97

10-
Native
11-
------
12-
13-
### MSVC / Visual Studio
14-
15-
JNA uses the free MS Visual Studio C++ Express compiler to compile
16-
native bits if MSVC is set in the environment. The MS compiler provides
8+
JNA uses the Microsoft Visual Studio C++ compiler (MSVC) to compile
9+
native bits when MSVC is detected in the environment. The MSVC compiler provides
1710
structured event handling (SEH), which allows JNA to trap native faults when
18-
run in protected mode.
11+
run in protected mode. It does this using libffi's `native/libffi/msvcc.sh`
12+
wrapper script, which converts Makefile `gcc` commands to MSVC-compatible
13+
(e.g. `cl.exe`, etc) calls.
1914

20-
On 64-bit windows, you will still need to install mingw64 in order to
15+
For x86, x86_64, you will still need to install mingw64 in order to
2116
compile a small bit of inline assembly.
2217

23-
To use the MS compiler, ensure that the appropriate 32-bit or 64-bit versions
24-
of cl.exe/ml.exe/ml64.exe/link.exe are in your PATH and that the INCLUDE and
25-
LIB environment variables are set properly (as in VCVARS.BAT).
26-
27-
Sample configuration setting up INCLUDE/LIB (see an alternative below):
18+
To use the MSVC compiler, the appropriate x86 or x86_64 versions
19+
of `cl.exe`/`ml(64).exe`/`link.exe` must be in your `PATH`
20+
and that the `INCLUDE` and `LIB` environment variables are set properly.
2821

29-
```shell
22+
We'll set these automatically using `VsDevCmd.bat`
23+
<details>
24+
<summary>Prefer to use <code>bash</code> instead?</summary>
25+
26+
```bash
3027
export MSVC="/c/Program Files (x86)/Microsoft Visual Studio 10.0/vc"
3128
export WSDK="/c/Program Files (x86)/Microsoft SDKs/Windows/v7.0A"
3229
export WSDK_64="/c/Program Files/Microsoft SDKs/Windows/v7.1"
3330

3431
export INCLUDE="$(cygpath -m "$MSVC")/include;$(cygpath -m "$WSDK")/include"
35-
# for 64-bit target
32+
# for x86_64 target
3633
export LIB="$(cygpath -m "$MSVC")/lib/amd64;$(cygpath -m "$WSDK_64")/lib/x64"
37-
# for 32-bit target
34+
# for x86 target
3835
export LIB="$(cygpath -m "$MSVC")/lib;$(cygpath -m "$WSDK")/lib"
3936
```
4037

41-
### mingw
42-
43-
Install [cygwin](http://www.cygwin.com/).
44-
45-
When installing cygwin, include ssh, git, make, autotools, and mingw{32|64}-g++.
46-
Ensure the mingw compiler (i686-pc-mingw32-gcc.exe or i686-pc-mingw64-gcc.exe) is on your path.
47-
48-
If `cl.exe` is found on your %PATH%, you'll need to invoke `ant native
49-
-DUSE_MSVC=false` in order to avoid using the MS compiler.
50-
51-
### Issues
52-
53-
#### Backslash R Command Not Found
54-
55-
If you get errors such as `'\r': command not found`, run `dos2unix -f [filename]`
56-
for each file that it's complaining about.
57-
58-
### Building
59-
60-
Type `ant` from the top to build the project.
61-
62-
Recipe for building on windows
63-
------------------------------
38+
**Warning:** The below steps are for `cmd` only. If you're choosing to use `bash`, you'll need to adjust each command as needed.
6439

65-
This is the contents of a note I made for myself to be able to build JNA on
66-
windows.
40+
</details>
6741

68-
This builds the library based on the Visual C++ compiler.
42+
### Prerequisites
43+
Starting pont: A clean Windows 10 64-bit Installation with all patches
6944

70-
<pre>
71-
0. Start-Point: A clean Windows 10 Installation with all patches as of 2019-07-30
72-
1. Install Visual C++ Build Tools 2019 (https://visualstudio.microsoft.com/de/downloads/)
73-
(Install "Windows 10 SDK", "MSVC v142 - VS 2019 C++-x64/x86-Buildtools", "Windows Universal CRT SDK")
74-
2. Install AdoptOpen JDK 8.0.222.10 (64 bit) (https://adoptopenjdk.net/index.html)
45+
1. Install Visual C++ Build Tools 2019 (https://visualstudio.microsoft.com/downloads/)
46+
* Install `Windows 10 SDK`, `MSVC v142 - VS 2019 C++-x64/x86-Buildtools`, `Windows Universal CRT SDK`
47+
2. Install AdoptOpenJDK 8.0.222.10 for the target architecture (https://adoptopenjdk.net/index.html)
48+
3. Install ant (https://ant.apache.org/bindownload.cgi).
7549
3. Install Cygwin 64 Bit (https://cygwin.com/install.html)
76-
- make
77-
- automake
78-
- automake1.15
79-
- libtool
80-
- mingw64-x86_64-gcc-g++ (Version 7.4.0-1)
81-
- mingw64-x86_64-gcc-core (Version 7.4.0-1)
82-
- gcc-g++
83-
- git
84-
4. Open a cmd for the following actions
85-
5. Point JAVA_HOME to the root of a 64 Bit JDK,
86-
set JAVA_HOME=c:\Program Files\AdoptOpenJDK\jdk-8.0.222.10-hotspot
87-
6. Ensure ant is accessible from the PATH
88-
set PATH=c:\temp\apache-ant-1.9.11\bin;%PATH%
89-
7, Include 64 Bit Cygwin in the path
90-
set PATH=c:\cygwin64\bin\;%PATH%
91-
8. Setup the Visual Studio build environment for 64 Bit builds
92-
"C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\Common7\Tools\VsDevCmd.bat" -arch=amd64
93-
9. Run native build
94-
95-
For 32bit:
96-
97-
0. Start-Point: A clean Windows 10 Installation with all patches as of 2019-07-30
98-
1. Install Visual C++ Build Tools 2019 (https://visualstudio.microsoft.com/de/downloads/)
99-
(Install "Windows 10 SDK", "VC++ 2017 Version 15.7 v14.14 toolset", "Windows Universal CRT SDK")
100-
2. Install AdoptOpen JDK 8.0.222.10 (32 bit) (https://adoptopenjdk.net/index.html)
101-
3. Install Cygwin 32 Bit (https://cygwin.com/install.html)
102-
- make
103-
- automake
104-
- automake1.15
105-
- libtool
106-
- mingw64-i686-gcc-g++ (Version 7.4.0-1)
107-
- mingw64-i686-gcc-core (Version 7.4.0-1)
108-
- gcc-g++
109-
- git
110-
4. Open a cmd for the following actions
111-
5. Point JAVA_HOME to the root of a 32 Bit JDK,
112-
set JAVA_HOME=c:\Program Files (x86)\AdoptOpenJDK\jdk-8.0.222.10-hotspot
113-
6. Ensure ant is accessible from the PATH
114-
set PATH=c:\temp\apache-ant-1.9.11\bin;%PATH%
115-
7, Include 32 Bit Cygwin in the path
116-
set PATH=c:\cygwin\bin\;%PATH%
117-
8. Setup the Visual Studio build environment for 32 Bit builds
118-
"C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\Common7\Tools\VsDevCmd.bat" -arch=x86
119-
9. Run native build
120-
</pre>
121-
122-
To build without Visual C++, using only Cygwin, just skip steps 1 and 5.
50+
- `make`, `automake`, `automake1.15`, `libtool`
51+
- `git`
52+
- `gcc-g++` (See table)
53+
| x86_64 | x86 | aarch64 |
54+
|----------|-------|-----------|
55+
| `gcc-g++`<br>`mingw64-x86_64-gcc-g++` <br>`mingw64-x86_64-gcc-core` | `gcc-g++`<br>`mingw64-i686-gcc-g++` <br>`mingw64-i686-gcc-core` | `gcc-g++` |
56+
57+
### Steps
58+
59+
1. Open `cmd` for the following actions
60+
2. Point `JAVA_HOME` to the root of the target JDK:
61+
#### JAVA_HOME `x86_64`
62+
```cmd
63+
set JAVA_HOME=C:\Program Files\AdoptOpenJDK\jdk-8.0.222.10-hotspot
64+
```
65+
66+
#### JAVA_HOME `x86`
67+
```cmd
68+
set JAVA_HOME=C:\Program Files (x86)\AdoptOpenJDK\jdk-8.0.222.10-hotspot
69+
```
70+
71+
#### JAVA_HOME `aarch64`
72+
Native builds only. For cross-compiling, use [`x86_64`](#JAVA_HOME-x86_64).
73+
```cmd
74+
set JAVA_HOME=%USERPROFILE%\jdk-16-ea+19-windows-aarch64
75+
```
76+
77+
3. Ensure `ant` is accessible from the `PATH`
78+
```cmd
79+
set PATH=%USERPROFILE%\apache-ant-1.9.11\bin;%PATH%
80+
```
81+
4. Include 64 Bit Cygwin in the path
82+
```cmd
83+
set PATH=C:\cygwin64\bin\;%PATH%
84+
```
85+
5. Setup the Visual Studio build environment using `vcvarsall` in `<host>_<target>` notation:
86+
#### VsDevCmd `x86_64`
87+
```cmd
88+
"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64
89+
```
90+
91+
#### VsDevCmd `x86`
92+
```cmd
93+
"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64_x86
94+
```
95+
96+
#### VsDevCmd `aarch64`
97+
```cmd
98+
"C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" x64_arm64
99+
```
100+
101+
6. Run the build
102+
```cmd
103+
ant
104+
```
105+
106+
... or if cross-compiling, specify the target architecture, e.g:
107+
```cmd
108+
ant -Dos.prefix=win32-aarch64
109+
```
110+
111+
### Mingw Only
112+
113+
To build without Visual C++, using only Cygwin, just skip step 5 and skip installing the Visual C++ Build Tools 2019 . (Cygwin currently cannot build `aarch64` binaries, MSVC is needed)
114+
115+
### Troubleshooting
116+
117+
1. For native compiling or linking errors for MSVC builds after `VsDevCmd.bat` was run for a different/wrong architecture:
118+
- Close and reopen `cmd`
119+
- Configure `PATH`, `JAVA_HOME` again per target architecture.
120+
- Run `ant clean`
121+
- Start the build again.
122+
1. For native compiling or linking errors for MSVC builds, toggle on debug mode in `native/libffi/msvcc.sh`:
123+
```diff
124+
- verbose=
125+
+ verbose=1
126+
```
127+
2. Re-run ant with detailed output:
128+
```
129+
ant -DEXTRA_MAKE_OPTS="--debug=v"
130+
```

0 commit comments

Comments
 (0)