diff --git a/.gitignore b/.gitignore index 2beafa5..2e50041 100644 --- a/.gitignore +++ b/.gitignore @@ -18,6 +18,7 @@ JacobVersion.properties setenv.sh junit*properties ~$* +settings.json /out /.idea diff --git a/README.md b/README.md index d893289..cc58a50 100644 --- a/README.md +++ b/README.md @@ -47,21 +47,21 @@ See [ReleaseNotes](docs/ReleaseNotes.md) for a full history. #### Tracked Changes 1.21 -| Item | Description | -| ------------------------------------------------------ | ----------------------------------------------- | -| **Bugs** | | -| https://github.com/freemansoft/jacob-project/issues/35 | Add Iterable to EnumVariant | -| https://github.com/freemansoft/jacob-project/issues/36 | Memory Leak | -| https://github.com/freemansoft/jacob-project/issues/38 | Implement Comparable on Currency | -| https://github.com/freemansoft/jacob-project/issues/40 | Incorrect delete in Dispatch JNI Invoke() | -| https://github.com/freemansoft/jacob-project/issues/42 | ArrayIndexOutOfBounds SafeArray | -| https://github.com/freemansoft/jacob-project/issues/43 | Memory Leaks in DispatchEvents.cpp | -| https://github.com/freemansoft/jacob-project/issues/45 | SaveArray init0 | -| https://github.com/freemansoft/jacob-project/issues/48 | Incorrect multi dimensional array element count | -| | | -| **Patches** | | -| none | none | -| | | -| **Feature Requests** | | -| none | none | +| Item | Description | +| -------------------------------------------------------- | ----------------------------------------------- | +| **Bugs** | | +| | Add Iterable to EnumVariant | +| | Memory Leak | +| | Implement Comparable on Currency | +| | Incorrect delete in Dispatch JNI Invoke() | +| | ArrayIndexOutOfBounds SafeArray | +| | Memory Leaks in DispatchEvents.cpp | +| | SaveArray init0 | +| | Incorrect multi dimensional array element count | +| | | +| **Patches** | | +| none | none | +| | | +| **Feature Requests** | | +| none | none | diff --git a/docs/BuildingJacobFromSource.md b/docs/BuildingJacobFromSource.md index 1fe1938..aba4325 100644 --- a/docs/BuildingJacobFromSource.md +++ b/docs/BuildingJacobFromSource.md @@ -47,25 +47,24 @@ The simplest build environment includes MS Visual Studio 16.0 (Studio 2019), Ecl * Let it detect the JDK * ANT plugin - -| | | | | | | -| --------- | ---------------------------------------- | ------------ | ----------------------- | --------------------------- | -------------- | -| Release | C Version | Java Version | ANT Version | Java IDE | generated DLLs | -| up to 1.6 | VC 98 (6.0) | ? | MAKE | Eclipse ? | 32 bit | -| 1.7 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse ? | 32 bit | -| 1.8 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse ? | 32 bit | -| 1.9 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse ? | 32 bit | -| 1.10 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse 3.?? | 32 bit | -| 1.11 | VC 98 (6.0) & 2003 64bit libs | 1.4.? (48) | 1.6.? | Eclipse 3.2.1 | 32 and 64 bit | -| 1.12 | VC 98 (6.0) & 2003 64bit libs | 1.4.2 (48) | 1.6.5 | Eclipse 3.2.2 | 32 and 64 bit | -| 1.13 | VC 2005 (8) | 1.4.2 (48) | 1.7.0 | Eclipse 3.3 | 32 and 64 bit | -| 1.14 | VC 2005 (8) | 1.5.0 (49) | 1.7.0 | Eclipse 3.3 | 32 and 64 bit | -| 1.15 | VC 2005 (8) | 1.5.0 (49) | 1.7.0 | Eclipse 3.4 | 32 and 64 bit | -| 1.17 | VC 2005 (8) | 1.5.0 (49) | 1.8.4 Eclipse Embedded | Eclipse 4.3 | 32 and 64 bit | -| 1.18 | VS 2013 (12) Windows SDK 7.1A | 1.6.0 (50) | 1.8.4 Eclipse Embedded | Eclipse 4.3 | 32 and 64 bit | -| 1.19 | VS 2013 (12) Windows SDK 7.1A | 1.8.0 (52) | 1.10.1 Eclipse Provided | Eclipse 4.7 | 32 and 64 bit | -| 1.20 | VS 2019 (16) Windows SDK 10 | 1.8.0 (52) | 1.10.8 Eclipse Provided | Eclipse 2020 09 | 32 and 64 bit | -| 1.21 | VS 2022 (17) Windows SDK 11 10.0.22621.0 | 17 | ?? | IntelliJ Community 2023.3.5 | 32 and 64 bit | +| | | | | | | +| --------- | ---------------------------------------- | ------------ | ----------------------- | --------------- | -------------- | +| Release | C Version | Java Version | ANT Version | Java IDE | generated DLLs | +| up to 1.6 | VC 98 (6.0) | ? | MAKE | Eclipse ? | 32 bit | +| 1.7 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse ? | 32 bit | +| 1.8 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse ? | 32 bit | +| 1.9 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse ? | 32 bit | +| 1.10 | VC 98 (6.0) | 1.4 (48) | 1.? | Eclipse 3.?? | 32 bit | +| 1.11 | VC 98 (6.0) & 2003 64bit libs | 1.4.? (48) | 1.6.? | Eclipse 3.2.1 | 32 and 64 bit | +| 1.12 | VC 98 (6.0) & 2003 64bit libs | 1.4.2 (48) | 1.6.5 | Eclipse 3.2.2 | 32 and 64 bit | +| 1.13 | VC 2005 (8) | 1.4.2 (48) | 1.7.0 | Eclipse 3.3 | 32 and 64 bit | +| 1.14 | VC 2005 (8) | 1.5.0 (49) | 1.7.0 | Eclipse 3.3 | 32 and 64 bit | +| 1.15 | VC 2005 (8) | 1.5.0 (49) | 1.7.0 | Eclipse 3.4 | 32 and 64 bit | +| 1.17 | VC 2005 (8) | 1.5.0 (49) | 1.8.4 Eclipse Embedded | Eclipse 4.3 | 32 and 64 bit | +| 1.18 | VS 2013 (12) Windows SDK 7.1A | 1.6.0 (50) | 1.8.4 Eclipse Embedded | Eclipse 4.3 | 32 and 64 bit | +| 1.19 | VS 2013 (12) Windows SDK 7.1A | 1.8.0 (52) | 1.10.1 Eclipse Provided | Eclipse 4.7 | 32 and 64 bit | +| 1.20 | VS 2019 (16) Windows SDK 10 | 1.8.0 (52) | 1.10.8 Eclipse Provided | Eclipse 2020 09 | 32 and 64 bit | +| 1.21 | VS 2022 (17) Windows SDK 11 10.0.22621.0 | 17 | VSCode provided | VSCode | 32 and 64 bit | Microsoft Visual Studio 2019 supports 64 bit builds. so no additional tools are required. @@ -85,7 +84,56 @@ The build process is based on ANT. You can run ANT from inside of eclipse or fro * **test** runs all the tests * One of the Excel unit tests is hard coded against Office 2019 32 bit. -## Eclipse Java IDE +## Visual Studio IDE + +You can open `jacob-project` in VS Code + +1. Open VS Code +2. Install the Java extensions +3. Install the ANT extension +4. Open the jacob project directory +5. Run the ANT default target to build the pieces + +### Running tests in VS Code with ANT + +The tests now sit in src/test. You can run all the tests with the `ANT target runner` if you installed the extension + +### Running tests in VS Code with the test runner. + +1. Build the dll and compile the java code using the default `Ant` target. +2. Create a `.vscode/settings.json` file with the following configuration in it. This makes the Jacob DLL accessible to the tests by setting `java.library.path` +3. Adjust the java location to your JDK location +4. You can now run any of the tests from the Test Runner panel. Debugging and breakpoints should work + +```json +{ + "java.configuration.runtimes": [ + { + "name": "JavaSE-1.8", + "path": "C:\\Program Files\\Amazon Corretto\\jdk1.8.0_372" + } + ], + "java.test.defaultConfig": "64bitDll", + "java.test.config": [ + { + "name": "64bitDll", + "workingDirectory": "${workspaceFolder}", + "classPaths": [ + "${workspaceFolder}/release/java", + "${workspaceFolder}/lib/hamcrest-2.2.jar", + "${workspaceFolder}/lib/junit-4.13.jar" + ], + + "vmargs": ["-Djava.library.path=${workspaceFolder}\\release\\x64"] + } + ] +} +``` + + +## Eclipse Java IDE (OBSOLETE) + +**The tests have moved from `unittest` to `src/test`** since these instructions were written You can open the jacob-project in Eclipse. @@ -150,4 +198,4 @@ export JAVA_HOME *** Last Modified 09/2020 1.19 -Converted from HTML to md 9/2020 \ No newline at end of file +Converted from HTML to md 9/2020 diff --git a/docs/UsingJacob.md b/docs/UsingJacob.md index f892991..6115974 100644 --- a/docs/UsingJacob.md +++ b/docs/UsingJacob.md @@ -22,7 +22,7 @@ Section not yet written. ## The Jacob DLL -Jacob.jar relies on a DLL file that it loads off of the library path or classpath. This means that you must either copy the appropriate jacob dll into your path or use VM options to add directory holding jacob dll to the path. Prior to 1.14M6, the jacob DLL name was always "jacob.dll". This made it hard to verify jacob was loading the correct dll when multiple copies of jacob were installed on a single system. It also was confusing on 64 bit systems where the 32 bit and 64 bit dlls have the same tames. Starting in 1.14M6, Jacob's library loader selects a dll with the appropriate name based on the jacob release and platform. The dll naming convention is: +Jacob.jar relies on a DLL file that it loads off of the library path or classpath. This means that you must either copy the appropriate jacob dll into your path or use VM options to add directory holding jacob dll to the path. Prior to 1.14M6, the jacob DLL name was always "jacob.dll". This made it hard to verify jacob was loading the correct dll when multiple copies of jacob were installed on a single system. It also was confusing on 64 bit systems where the 32 bit and 64 bit dlls have the same tames. Starting in 1.14M6, Jacob's library loader selects a dll with the appropriate name based on the jacob release and platform. The dll naming convention is: `jacob..dll` Classloader issues @@ -39,9 +39,10 @@ Jacob 1.13 is built with VC++ 2005 that creates a dependency on msvcr80.dll. Win If you see the following message then you probably don't have the right C++ libraries. -
	Exception in thread "main" java.lang.UnsatisfiedLinkError: C:\apps\...\jacob.dll: This application has 
-	failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem 
-
+```txt +Exception in thread "main" java.lang.UnsatisfiedLinkError: C:\apps\...\jacob.dll: This application has + failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem +``` [Visual C redistributable installer SP1](http://www.microsoft.com/downloads/details.aspx?familyid=200B2FD9-AE1A-4A14-984D-389C36F85647&displaylang=en) @@ -108,7 +109,7 @@ Setting this flag to false causes Jacob to check the and .PutInROT p .PutInROT -Lets a program specify that instances of certain classes are to not be inserted into the ROT. This experimental (1.13) feature provides a mechanism for freeing VariantViaEvent objects that are created in Event threads. There is normally no way to free those objects because the thread terminates outside of any normally MTA/STA Startup/Teardown code. Each event occurs in a new thread and creates a new ROT entry so they grow without bounds.This option may cause VM crashes in certain situations where windows memory is freed outside of the thread it was created in but empirical evidence shows there are situations where this great reduces the long running memory footprint of applications that process a lot of events. _This function is still experimental_. The functionality was added 1.13\. Some of this overlaps the experimental `com.jacob.autogc` introduced in 1.9\. See the ROT.java test program for an example of the effects of this option.This value is checked every time and can be changed on-the-fly via `System.setProperty();`Example: `System.setProperty("com.jacob.com.VariantViaVariant.PutInROT","false");` +Lets a program specify that instances of certain classes are to not be inserted into the ROT. This experimental (1.13) feature provides a mechanism for freeing VariantViaEvent objects that are created in Event threads. There is normally no way to free those objects because the thread terminates outside of any normally MTA/STA Startup/Teardown code. Each event occurs in a new thread and creates a new ROT entry so they grow without bounds.This option may cause VM crashes in certain situations where windows memory is freed outside of the thread it was created in but empirical evidence shows there are situations where this great reduces the long running memory footprint of applications that process a lot of events. _This function is still experimental_. The functionality was added 1.13\. Some of this overlaps the experimental `com.jacob.autogc` introduced in 1.9\. See the ROT.java test program for an example of the effects of this option.This value is checked every time and can be changed on-the-fly via `System.setProperty();`Example: `System.setProperty("com.jacob.com.VariantViaVariant.PutInROT","false");` Example: `-Dcom.jacob.com.VariantViaVariant.PutInROT=false` @@ -132,15 +133,47 @@ Example: `-Dcom.jacob.com.VariantViaVariant.PutInROT=false` -*** ## Finding the DLL version using windows command line The jacob.dll file includes the jacob release number in the version field. Run the following from the command prompt `dumpbin /version jacob.dll` . The dll version number is stored in the "image version" field of the "OPTIONAL HEADER VALUES" section. This information from [The Microsoft msdn web site](http://msdn2.microsoft.com/en-gb/library/h88b7dc8(VS.71).aspx) -*** ## Unit Tests -Jacob must know the location of the DLL when running the unit tests in Eclipse. The simplest way to do this is to add the dll path to the unit as a VM argument. The argument should be specified based on where you installed the jacob source package. If you have jacob unpacked in c:/dev/jacob and built using build.xml, then the vm arguments would be: -`-Djava.library.path=c:/dev/jacob/release/x86` .Last Modified 4/2008 1.15 \ No newline at end of file +Jacob must know the location of the DLL when running the unit tests from the command line or inside an IDE. +The simplest way to do this is to add the dll path to the unit as a VM argument. +The argument should be specified based on where you installed the jacob source package. +If you have jacob unpacked in c:/dev/jacob and built using build.xml, then the vm arguments would be: +`-Djava.library.path=c:/dev/jacob/release/x86` . + +If you are running it from inside a test runner in an IDE like VSCode. Then you need to set up the runner to pass the DLL library location to all the tests +using `-Djava.library.path` + +This is a sample workspace settings.json fragment that configures the dll and jars for the tests. + +```json +{ + "java.configuration.runtimes": [ + { + "name": "JavaSE-1.8", + "path": "C:\\Program Files\\Amazon Corretto\\jdk1.8.0_372" + } + ], + "java.test.defaultConfig": "64bitDll", + "java.test.config": [ + { + "name": "64bitDll", + "workingDirectory": "${workspaceFolder}", + "classPaths": [ + "${workspaceFolder}/release/java", + "${workspaceFolder}/lib/hamcrest-2.2.jar", + "${workspaceFolder}/lib/junit-4.13.jar" + ], + + "vmargs": ["-Djava.library.path=${workspaceFolder}\\release\\x64"] + } + ] +} + +```