First draft update basic query to use VS Code

(cherry picked from commit 3e0702f)

Author: felicitymay

docs/codeql/codeql-language-guides/basic-query-for-cpp-code.rst

@@ -3,7 +3,9 @@
 Basic query for C and C++ code
 ==============================
 
-Learn to write and run a simple CodeQL query using LGTM.
+Learn to write and run a simple CodeQL query using Visual Studio Code with the CodeQL extension.
+
+.. include:: ../reusables/setup-to-run-queries.rst
 
 About the query
 ---------------
@@ -14,62 +16,65 @@ The query we're going to run performs a basic search of the code for ``if`` stat
 
    if (error) { }
 
-Running the query
------------------
-
-#. In the main search box on LGTM.com, search for the project you want to query. For tips, see `Searching <https://lgtm.com/help/lgtm/searching>`__.
+Finding a CodeQL database to experiment with
+--------------------------------------------
 
-#. Click the project in the search results.
+Before you start writing queries, you need a CodeQL database to run them against. The simplest way to do this is to download a database directly from GitHub.com.
 
-#. Click **Query this project**.
+#. In Visual Studio Code, click the **QL** icon |codeql-ext-icon| in the left sidebar to display the CodeQL extension. 
 
-   This opens the query console. (For information about using this, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__.)
+#. Click **From GitHub** or the GitHub logo |github-db| at the top of the CodeQL extension to open an entry field.
 
-   .. pull-quote::
+#. Copy the URL for the repository into the field and press the keyboard **Enter** key.
 
-      Note
+#. Optionally, if the repository has more than one CodeQL database available, choose which language to download.
 
-      Alternatively, you can go straight to the query console by clicking **Query console** (at the top of any page), selecting **C/C++** from the **Language** drop-down list, then choosing one or more projects to query from those displayed in the **Project** drop-down list.
-
-#. Copy the following query into the text box in the query console:
-
-   .. code-block:: ql
+Information about the progress of the database download is shown in the bottom right corner of Visual Studio Code. When the download is complete, the database is shown with a check mark in the **Databases** section of the CodeQL extension.
 
-      import cpp
+.. image:: ../images/codeql-for-visual-studio-code/database-selected.png
+       :align: center
+       :width: 500
 
-      from IfStmt ifstmt, BlockStmt block
-      where ifstmt.getThen() = block and
-        block.getNumStmt() = 0
-      select ifstmt, "This 'if' statement is redundant."
+Running the query
+-----------------
 
-   LGTM checks whether your query compiles and, if all is well, the **Run** button changes to green to indicate that you can go ahead and run the query.
+#. In Visual Studio Code, create a new folder to store your experimental queries for C and C++ CodeQL databases. For example, ``cpp-experiments``.
 
-#. Click **Run**.
+#. Create a ``qlpack.yml`` file in your experiments folder with the contents shown below. This tells the CodeQL extension that any queries you create in the folder are intended to run on C or C++ CodeQL databases.
 
-   The name of the project you are querying, and the ID of the most recently analyzed commit to the project, are listed below the query box. To the right of this is an icon that indicates the progress of the query operation:
+   .. code-block:: yaml
 
-   .. image:: ../images/query-progress.png
-       :align: center
+      name: github-owner/cpp-experiments
+      version: 0.0.1
+      dependencies:
+         codeql/cpp-all: ^0.1.2
 
-   .. pull-quote::
+#. Create a second new file in your experiements folder with the ``.ql`` file extension. You will write your first query in this file.
 
-      Note
+#. Copy the following query into the new file and save the file:
 
-      Your query is always run against the most recently analyzed commit to the selected project.
+   .. code-block:: ql
 
-   The query will take a few moments to return results. When the query completes, the results are displayed below the project name. The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs. The second column is the alert message.
+      import cpp
 
-   ➤ `Example query results <https://lgtm.com/query/4242591143131494898/>`__
+      from IfStmt ifstmt, BlockStmt block
+      where ifstmt.getThen() = block and
+        block.getNumStmt() = 0
+      select ifstmt, "This 'if' statement is redundant."
 
-   .. pull-quote::
+#. Right-click in the query window and select **CodeQL: Run Query**. (Alternatively, run the command from the Command Palette.)
 
-      Note
+   The query will take a few moments to return results. When the query completes, the results are displayed in a CodeQL Query Results window, alongside the query window.
+   
+   The query results are listed in two columns, corresponding to the two expressions in the ``select`` clause of the query. The first column corresponds to the expression ``ifstmt`` and is linked to the location in the source code of the project where ``ifstmt`` occurs. The second column is the alert message.
 
-      An ellipsis (…) at the bottom of the table indicates that the entire list is not displayed—click it to show more results.
+.. image:: ../images/codeql-for-visual-studio-code/basic-cpp-query-results-1.png
+    :align: center
 
-#. If any matching code is found, click a link in the ``ifstmt`` column to view the ``if`` statement in the code viewer.
+If any matching code is found, click a link in the ``ifstmt`` column to open the file and highlight the matching ``if`` statement.
 
-   The matching ``if`` statement is highlighted with a yellow background in the code viewer. If any code in the file also matches a query from the standard query library for that language, you will see a red alert message at the appropriate point within the code.
+.. image:: ../images/codeql-for-visual-studio-code/basic-cpp-query-results-2.png
+    :align: center
 
 About the query structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -120,7 +125,7 @@ In this case, identifying the ``if`` statement with the empty ``then`` branch as
 
 To exclude ``if`` statements that have an ``else`` branch:
 
-#. Extend the ``where`` clause to include the following extra condition:
+#. Edit your query and extend the ``where`` clause to include the following extra condition:
 
    .. code-block:: ql
 
@@ -134,14 +139,20 @@ To exclude ``if`` statements that have an ``else`` branch:
         block.getNumStmt() = 0 and
         not ifstmt.hasElse()
 
-#. Click **Run**.
+#. Re-run the query.
 
    There are now fewer results because ``if`` statements with an ``else`` branch are no longer reported.
 
-➤ `See this in the query console <https://lgtm.com/query/1899933116489579248/>`__
-
 Further reading
 ---------------
 
 .. include:: ../reusables/cpp-further-reading.rst
 .. include:: ../reusables/codeql-ref-tools-further-reading.rst
+
+.. |codeql-ext-icon| image:: ../images/codeql-for-visual-studio-code/codeql-extension-icon.png
+  :width: 20
+  :alt: Icon for the CodeQL extension.
+
+.. |github-db| image:: ../images/codeql-for-visual-studio-code/add-codeql-db-github.png
+  :width: 20
+  :alt: Icon for the CodeQL extension option to download a CodeQL database from GitHub.

docs/codeql/images/codeql-for-visual-studio-code/add-codeql-db-github.png

@@ -0,0 +1 @@
+For information about installing the CodeQL extension for Visual Studio code, see ":ref:`Setting up CodeQL in Visual Studio Code <setting-up-codeql-in-visual-studio-code>`."