Installation Recipes
- How to install VStar under Windows
- How to install VStar under Mac OS X
- How to install VStar under Linux or other environments in which a bash shell can be used
- Command-line options
- Plug-ins
Prerequisites: VStar is a Java-based application. It requires Java Runtime Environment (JRE) version 1.8 or later. You can download JRE installer for free from the official site: https://www.java.com/en/download/
Vstar for Windows is distributed in a form of a ZIP-package (requires manual installation) and as an executable installer. Both packages can be downloaded from the GitHub repository.
Go to https://github.com/AAVSO/VStar/releases. Select the newest release available. You will see a list of installation packages. For Windows, as mentioned before, two types of packages are available: ZIP-package (vstar-(version)-win.zip) and executable installer (also zipped: VStarWinSetup-(version).zip).
Download vstar-(version)-win.zip. Unpack it into the desired location (for example, to the Documents folder or to your home folder). Inside the vstar folder, find the VStar.exe executable file and launch it like any other application. You can also create desktop and user menu shortcuts to VStar.exe launching CreateVStarShortcuts.vbs script.
It is also recommended to update memory-related parameters in VStar.ini file. You can do it automatically by launching VStar.exe with the //restore parameter from the command line:
VStar.exe //restore
Download and unpack VStarWinSetup-(version).zip. Launch unpacked VStarWinSetup-(version).exe. In most cases, you can simply follow the installation wizard. In the beginning, the installer checks if JRE is installed (trying to execute javaw.exe) and prompts you to download JRE if an attempt to launch javaw.exe fails.
Along with the VStar core, the installer writes a default set of JAR plugin files into the 'vstar_plugins' folder located in your home folder. Any existing plugin JAR files will be overwritten. If you uncheck the appropriate flag during the installation, the plugins will not be installed. You can always install the most recent versions of the plugins from within VStar, see the documentation.
The installer creates a desktop shortcut (labeled “AAVSO VStar”) and VStar program group in the Windows Start menu.
This program group contains a shortcut to VStar, a shortcut to VStar.ini ("VStar launcher configuration"), and “VStar Debug Mode” to diagnose possible startup errors (see also “Troubleshooting memory problems”). "Restore Default Memory Options" writes JVM memory configuration parameters into VStar.ini that corresponds to the PC's installed memory size.
Sometimes VStar may not start because of memory allocation errors. If you encountered this, please use the “Debug Mode VStar” shortcut from VStar program group in the Windows Start menu. If you see a message like this:
please open VStar.ini (using a shortcut from VStar program group) and comment out the “Parameters=” line:
Save VStar.ini and try to launch VStar again using the “AAVSO VStar” shortcut. If VStar runs normally, you can try to uncomment the “Parameters=” line and decrease the value of -Xmx parameter.
Sometimes, the system restricts Java VM memory usage via environment variable _JAVA_OPTIONS. You can inspect it running VStar in a debug mode using the “Debug Mode VStar” shortcut from the VStar program group as described above. If _JAVA_OPTIONS environment variable exists, you will see something like this:
In this example, _JAVA_OPTIONS restricts Java VM memory so it will not use more than 1Gb memory regardless of actual available memory size and VStar.ini settings. It is recommended to remove such a limitation:
Press Win+R. This will launch the 'Run' applet. Insert the following command line into it and click OK:
rundll32.exe sysdm.cpl,EditEnvironmentVariables
This will launch Windows Environment Variables applet. Find _JAVA_OPTIONS variable and edit or delete it. The system must be restarted to activate changes.
Open vstar-mac.dmg and copy the VStar application to a location of your choice, along with the Extras folder if desired.
Double-click the VStar launcher application to run VStar.
On the first run after download, you may need to open VStar with ctrl-click (hold the control key down then click the trackpad/mouse). You will be presented with a dialog that says:
“VStar” can’t be opened because Apple cannot check it for malicious software.
Select the Open button in this dialog and VStar will start. The next time you start VStar, simply double-clicking to open should be all that's needed.
Extract vstar-bash.zip to a location of your choice.
Run the VStar.sh shell script from the command-line: ./VStar.sh
Since Mac OS X has a Terminal application with bash, vstar-bash.zip can also be used on the Mac if so desired. See the next section for one motivation to do so.
Each section above provides instructions for how to run VStar from the command-line (VStar.exe or VStar.sh).
When run in this way, a number of command-line options are available:
- --help
- --default-look-and-feel
- --noplugins
- --script path
The bash script is used in the description of each option that follows.
Typing ./VStar.sh --help gives command-line usage information:
usage: vstar [--default-look-and-feel] [--noplugins] [--script path]
Typing ./VStar.sh --default-look-and-feel will run VStar with the default Java (non-OS specific) look and feel.
Typing ./VStar.sh --noplugins in a bash shell will run VStar with no plug-ins loaded.
A script can be run when VStar starts by typing ./VStar.sh --script path where path is the relative or absolute path to a script file. See the VStar user manual for more about scripting VStar.
Further, another Windows specific command-line option (//restore) is also described in the How to install VStar under Windows section.
The functionality of VStar is extendable with plug-ins. There are plenty of plug-ins available, you can find an instruction on how to use and install plug-ins here: https://aavso.org/vstar-plugin-library
Warning! After installing the new version of VStar, check "Plug-in location base URL" in Preferences. The remote plug-in directory version should be the same as the VStar version. For example, if you use VStar 2.21.3, the URL should point to vstar-plugins-2.21.3.
It is also possible to install plug-ins from a local zip file. See the VStar user manual for details.