Chapter 1
Setting everything up
In this chapter, you will install X# and I will give you a short overview of the different options. If you want to start programming, please skip this chapter. The easiest way to install X# is to click through the setup and a few minutes later you can start Visual Studio, choose a template, and start coding.
Installation of X#
The current 2.x version of X# has to be downloaded and installed from the official X# website. This version is only available for Windows. The download consists of a zip file that contains a Windows installer file.
The address of the X# website is https://www.xsharp.eu
The first step is to log in or register first. No download without login first.
The next step is to visit the Downloads section.
Now comes an important distinction. X# is free and open source, but there is also a private version for subscribers ("Friends of XSharp", FoX for short) which is not free and costs some money. The idea is, that anybody who uses X# professionally should pay a subscription fee every year to support the developer team and to get better support if needed.
If you are a professional developer who makes a living with programming with X#, please consider buying a license (it's like giving some money to your favorite charity organization and we all know that giving to a good cause makes us happier ;)
The address of the project portal that contains the public repository for the source code for the XSharp Runtime, Project System, and Tool is https://github.com/X-Sharp.
The address for the source code of the X# compiler is https://github.com/X-Sharp/XSharpDev.
Important: Both addresses are only of interest to developers who like to read, analyze, or even contribute to the X# compiler code or want to report bugs directly to the developers. For general questions, suggestions, or any other kind of comment or discussion the X# forum is a much better place. Eventually, every forum post will be answered by one of the X# team members sooner or later.
For this guide, the public version of X# will be used like "XSharp Cahors 2.13 public installer".
Extract the zip archive into a temp folder. The zip archive only contains a single exe file, eg. XSharpSetupPublic2.13.2.2.exe.
This may sound like a humorous remark, but if you forget to install Visual Studio before the installation, the setup program asks if it should downloaded it for you (I have to admit that I have never tried this option yet).
Fig 1.1: If Visual Studio is not installed, the friendly people from X# will download it for you
Double-click on the exe file to start the installation.
Choose Next to skip the welcome screen.
Accept the license agreement and choose Next to continue.
Read the information box and choose Next to continue.
Either confirm the installation directory C:\Program Files (x86)\XSharp or choose another directory and choose Next to continue.
NOTE: The default behavior of the installer is to uninstall a previous version (the version number doesn't matter). How to avoid this "restriction" will be revealed at the end of this chapter.
Fig 1.2: Confirming or choosing the path of the X# application directory
Either confirm the preselected choice of X# components or make changes to the selection. Usually, there is no need to change the selection, but there might be a reason to do so:
- XIDE should (not) be installed
- The Net Core compiler should (not) be installed (it's not part of the public version anymore)
- No Visual Studio integration should or can be installed because only the X# compiler is needed
- The examples are not needed
- The PRG extension should not be registered
- There is no need for the native image
- The X# assemblies should not be part of the Global Assembly Cache (GAC)
The two important choices concern the XIDE for X# and the additional installation of the .Net Core compiler.
Fig 1.3: Choosing the components for the X# installation
Choose Next to continue.
Either confirm or change the name of the shortcut in the program menu.
Choose Next to continue.
Choose Install to finally start the installation.
If Visual Studio is still running, the installation will stop and the installer will ask for allowance to automatically end and later restart Visual Studio. This is most of the time the only option because the installer always uninstalls a previous installation of X# first and if the Visual Studio integration had been installed, which is usually the case, the Visual Studio integration should be uninstalled too which is only possible if Visual Studio is not currently running. The other option to not close Visual Studio is not an option most of the time.
Fig 1.4: The X# installation is on its way
It will take a few minutes until the installation is complete. Taking a look at the Whatsnew.pdf file is recommended because it lists all the new features of the latest release as well as the new features of previous releases.
It is always recommended to inspect the program directory after a successful installation. Tab 1.1 contains the subdirectories with a short description of its content.
| Subdirectory | Content |
|---|---|
| Assemblies | All the assemblies needed for the compilation of X# source files |
| Bin | The X# compiler xsc.exe and a few other program files |
| Extension | The files for the Visual Studio integration (most notably the Vsix files to install the Visual Studio integration) |
| Help | The two help files (XSharp.chm and XSharpRef.chm) |
| Images | Some ico files |
| Include | Header file for user-defined commands (UDC) |
| MsBuild | The files needed for MSBuild |
| Redist | All the runtime files needed for redistributing X# programms |
| Uninst | The exe file for uninstalling X# |
| VOXPorter | The directory for the VOXPorter application |
| XIde | The directory for XIDE if the component had been selected in the setup dialog |
Tab 1.1: The subdirectories of the X# application directory
Where are the examples? Have a look in the documents folder. You will have a shortcut to another directory that contains the example projects.
Some troubleshooting tips
I don't know if this happened only to me (there were no other error reports in the X# forum at that time), but I had some trouble installing the Visual Studio Extension for Cahors 2.13 (for example) and Visual Studio 2022. The setup was completed without any errors, but the X# extension was not installed and therefore I couldn't load any Xsproj project files - an unfriendly error message was the result. To make another long story short, although I was not able to detect the source of the problem, I was finally able to activate the extension by directly installing the X# extension and reloading the X# project in the solution explorer.
Fig 1.5: You don't want to see this error message too often
You will find the vsix file in the XSharp installation directory (eg. D:\Program Files\XSharp\Extension\XSharpProject2022.vsix). Just double-click on the vsix file to install the extension. Then reload the X# project through the context menu in the solution explorer.
Fig 1.6: Reloading an XSharp project after the re-installation of the XSharp extension
And if the direct installation doesn't succeed either, delete an existing X# extension in the Visual Studio directory (eg. C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\Extensions) and give it another try.
So, the tip in this section is that in the rare case that the extension does not load automatically, do not give up easily but try some activities that might lead to the "promised land" of a working X# extension. The most promising (at least for me) option is to install the X# extension directly (but you really should not need to reinstall Visual Studio;).
But, please note, that should only be the last resort in a situation where you want to fix the problem immediately. A much better option is to report the problem in the X# forum.
TIP: There is a log file (ActivityLog.Setup.xml) that contains all the actions taken during the installation of a Visual Studio extension. The path depends on the Visual Studio version number (eg. %appdata%\Microsoft\VisualStudio\17.0_543ccb56). Although it's unlikely to find any hints about the real reason for the problem, it's always worth taking a closer look.
Installing the .Net Framework SDK
Some X# projects need tools like Ic.exe or AxImp.exe to complete the build process. These tools are part of the .Net Framework SDK which can either be installed through the Windows SDK (the version number should not matter) or through a separate download of that specific SDK. The .Net Framework SDK should be installed with the installation of Visual Studio anyway, but if for some obscure reason, the tools are not where they should be, it might take some effort to reinstall them (I once had to completely uninstall the Windows SDK and delete every folder belonging to that SDK to make the installer reinstall it). The path to the exe files of the .Net Framework SDK is something like C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.8 Tools.
Installing only the X# compiler
Its also possible to install X# without the Visual Studio integration. Not choosing the GAC option means that the XSharp assemblies are copied only in the installation directory.
Installing several versions of X
The default behavior of the setup program is to uninstall a previous version first. You can prevent this behavior by calling the setup program in the command line and adding the /nouninstall switch. This prevents the uninstallation of the previous version. So, if you choose a different folder, it's possible to install more than one X# version on a computer. But there can always be only one version installed inside Visual Studio.