Skip to content

Docs: Mention packaging commands in CodeQL extension #7661

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shati-patel merged 4 commits into from
Jan 25, 2022
Merged

Docs: Mention packaging commands in CodeQL extension #7661

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dc71ece
Docs: Mention packaging commands in CodeQL extension
shati-patel Jan 19, 2022
8fc429c
Emphasize use case for installing pack deps
shati-patel Jan 20, 2022
9e1e2ba
Apply suggestions from code review
shati-patel Jan 25, 2022
1462565
Clarify "download packs" usage
shati-patel Jan 25, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions ...deql-for-visual-studio-code/working-with-codeql-packs-in-visual-studio-code.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,12 @@ About CodeQL packs
------------------
CodeQL packs are used to create, share, depend on, and run CodeQL queries and libraries. You can publish your own CodeQL packs and download packs created by others. For more information, see ":ref:`About CodeQL packs <about-codeql-packs>`."

Installing dependencies for CodeQL packs in Visual Studio Code
Comment thread
shati-patel marked this conversation as resolved.
Outdated
--------------------------------------------------------------
To install dependencies for a CodeQL pack in your Visual Studio Code workspace, run the **CodeQL: Install Pack Dependencies** command from the Command Palette and select the packs you want to install dependencies for.
Copy link
Copy Markdown
Contributor

@felicitymay felicitymay Jan 21, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the demo gif, this is called CodeQL: Install Packs - I assume that the name changed since you recorded that?

Copy link
Copy Markdown
Contributor Author

@shati-patel shati-patel Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. sorry about that - the GIF is slightly outdated! We decided to change the command name to be more explicit 😺


In particular, installing pack dependencies lets you write and run query packs that depend on the CodeQL standard libraries, without needing to check out the standard libraries in your workspace.
Comment thread
shati-patel marked this conversation as resolved.
Outdated

Creating and editing CodeQL packs in Visual Studio Code
-------------------------------------------------------
To create a new CodeQL pack, you will need to use the CodeQL CLI from a terminal, which you can do within Visual Studio Code or outside of it with the ``codeql pack init`` command. Once you create an empty pack, you can edit the ``qlpack.yml`` file or run the ``codeql pack add`` command to add dependencies or change the name or version. For more information, see ":ref:`Creating and working with CodeQL packs <creating-and-working-with-codeql-packs>`."
Expand All @@ -23,8 +29,10 @@ You can then use the CodeQL CLI to publish your pack to share with others. For m

Viewing CodeQL packs and their dependencies in Visual Studio Code
-----------------------------------------------------------------
Whether you have used the CodeQL CLI to download a CodeQL pack that someone else has created, or created your own, you can open the ``qlpack.yml`` file in the root of a CodeQL pack directory in Visual Studio Code and view the dependencies section to see what libraries the pack depends on.
To download a CodeQL pack that someone else has created, run the **CodeQL: Download Packs** command from the Command Palette.
Copy link
Copy Markdown
Contributor

@felicitymay felicitymay Jan 21, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Having watched the gif (thanks), I wonder if we need to mention that you'll need to enter the full pack name and give an example. This may be obvious to the user but I wanted to check.

Copy link
Copy Markdown
Contributor

@felicitymay felicitymay Jan 21, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also - potentially, this deserves its own heading, even though it will be a very short section, to make it easier for users to find when they scan this article.

Copy link
Copy Markdown
Contributor Author

@shati-patel shati-patel Jan 25, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! I've added a bit of clarification and an example in 1462565 ⚡

Haven't added a new heading just yet, since we don't expect too many users to use this command at the moment. Once we've added a way to directly run queries from a downloaded pack, we can make this more discoverable! (Currently, they'd have to find the queries in their package cache, which isn't ideal...)


Whether you have downloaded a CodeQL pack or created your own, you can open the ``qlpack.yml`` file in the root of a CodeQL pack directory in Visual Studio Code and view the dependencies section to see what libraries the pack depends on.

If you want to understand a query in a CodeQL pack better, you can open the query file and view the code, using the IntelliSense code editing features of Visual Studio Code. For example, if you hover over an element from a library depended on by the pack, Visual Studio Code will resolve it so you can see documentation about the element.

To view the full definition of an element of a query, you can right-click and choose **Go to Definition**. If the library pack is present within the same Visual Studio Code workspace, this will take you to the definition within the workspace. Otherwise it will take you to the definition within your package cache, the shared location where downloaded dependencies are stored, which is in your home directory by default.
To view the full definition of an element of a query, you can right-click and choose **Go to Definition**. If the library pack is present within the same Visual Studio Code workspace, this will take you to the definition within the workspace. Otherwise it will take you to the definition within your package cache, the shared location where downloaded dependencies are stored, which is in your home directory by default.