===========================================
VSCode Extension Installation and Licensing
===========================================

Installation
============

Compatibility
-------------

The Lattix VSCode Extension is only compatible with **Lattix version 2025 or
greater**. If you are using an older version of Lattix, please contact
your Lattix supplier to discuss upgrading.

The VSCode Extension is licensed as an add-on to Lattix Architect, so will require
an **Lattix IDE license key**, in addition to a **Lattix Architect license key**.
Please contact your Lattix supplier for a Lattix IDE license key.

Please follow the steps outlined in :ref:`License Management` to add the Lattix IDE license key from within 
Lattix Architect.

Installing
----------

To install the Lattix VSCode extension:

#. Ensure that you have Lattix Architect already installed and licensed on your machine
#. Open VSCode
#. Open the VSCode Extension Marketplace by clicking on the Marketplace button in the sidebar
#. Search for **Lattix**
#. Click **Install**

The version of Lattix Architect installed on the user's machine will be detected, so that the correct version of the VSCode extension will be installed.

If Lattix Architect cannot be found, you will be prompted to specify its location:

|locationOfLattixInstall|

The usual location for a Lattix Architect install is ``/opt/Lattix`` for unix-like systems, and
``C:\Program Files\Lattix${VERSION}`` for Windows.

This location will be saved within the Settings of the Lattix VSCode Extension. In
the case that your Lattix installation location moves, or you wish to specify a
different installation location, you can edit this path:

#. Open the settings with keyboard shortcut ``CTRL+,``
#. Search for ``@ext:codeclinicllc.lattix``
#. Edit the path of the Location of Lattix Architect Install

|lattixInstallLocSettings|

.. note::
    The VSCode Extension requires line number information to function.
    Please include line number processing when creating the Lattix project
    to use the VSCode Extension.


Licensing
---------

Installing a Local License Key from within VSCode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are using a host-based license, this can be installed from within the VSCode IDE.

If the VSCode extension is started without a valid license, it will display the following message:

|ideNotLicensed|

Click **Yes** to open an input box at the top of the VSCode window where you can paste your **Lattix IDE license key**.

.. note::

   The input box is sensitive to losing focus and does not support pasting from the
   right-click context menu. If it loses focus it will close without saving your input.

   Copy your license key beforehand and paste it using **CTRL+V** (Windows/Linux) or
   **CMD+V** (macOS).

Manual setup of a local or floating license
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The steps for configuring a floating license can be found :ref:`here <Floating License Manager>`.

Once you have either a **host-based license key** or information about your company's **license server**, 
you can follow these steps to allow the Lattix VSCode Extension to access the license.

#. Locate your ``.lattix`` directory.

   The location is usually::

      ~/.lattix

   For example, on Windows this may be::

      C:/Users/<username>/.lattix

   .. note::

      The ``.lattix`` directory is hidden on most systems. You may need to enable
      *Show hidden files* in your file browser.

#. Create or open the file::

      ide.lic

#. Add text to the top of the file:

   a. For a **host-based license key**, add the license key text.

   b. To connect to a floating **license server**, add the following line::

         HOST <hostname> ANY <portnumber>

      Example::

         HOST 192.0.2.10 ANY 5053

      Note that 5053 is the default port number for a Lattix license server.

#. Save the file and restart VSCode.

.. |locationOfLattixInstall| image:: ./images/locationOfLattixInstall.png
.. |lattixInstallLocSettings| image:: ./images/vscode-lattixInstallLocSettings.png
.. |ideNotLicensed| image:: ./images/vscode-ide-not-licensed.png