Choose Your Preferred Tools ​

Command Line Interface (CLI) ​

Installed with @sap/cds-dk ​

To use cds from your command line install @sap/cds-dk globally:

npm i -g @sap/cds-dk

npm i -g @sap/cds-dk

cds version ​

Use cds version to get information about your installed package version

$ cds version
@capire/samples: 2.0.0
@sap/cds: 6.7.0
@sap/cds-compiler: 3.8.2
@sap/cds-dk: 6.7.0
@sap/cds-dk (global): 6.7.0
@sap/cds-mtxs: 1.7.1
@sap/eslint-plugin-cds: 2.6.3
Node.js: v18.13.0
home: .../node_modules/@sap/cds

$ cds version --markdown

| @capire/samples | https://github.com/sap-samples/cloud-cap-samples.git |
|:------------------ | ----------- |
| Node.js            | v18.13.0    |
| @sap/cds           | 6.7.0       |
| @sap/cds-compiler  | 3.8.2       |
| @sap/cds-dk        | 6.7.0       |
| @sap/eslint-plugin | 2.6.3       |

cds help ​

Use cds help to see an overview of all commands

$ cds help

USAGE

    cds <command> [<args>]
    cds <src>  =  cds compile <src>
    cds        =  cds help

COMMANDS

    i | init       jump-start cds-based projects
    a | add        add a feature to an existing project
    y | bind       bind application to remote services
    m | import     add models from external sources
    c | compile    compile cds models to different outputs
    p | parse      parses given cds models
    s | serve      run your services in local server
    w | watch      run and restart on file changes
    r | repl       read-eval-event loop
    e | env        inspect effective configuration
    b | build      prepare for deployment
    d | deploy     deploy to databases or cloud
    l | login      login to extendable SaaS application
    t | lint       [beta] run linter for env or model checks
    v | version    get detailed version information
    ? | help       get detailed usage information
      | pull       pull the base model for your SaaS app extension.
      | push       push your extension to the SaaS app in order to enable or update it
      | subscribe  subscribe a tenant to a multitenant SaaS app
      | mock       call cds serve with mocked service

  Learn more about each command using:
  cds help <command> or
  cds <command> --help

Use cds help <command> or cds <command> ? to get specific help

$ cds watch --help

SYNOPSIS

  cds watch [<project>]

  Tells cds to watch for relevant things to come or change in the specified
  project or the current work directory. Compiles and (re-)runs the server
  on every change detected.

  Actually, cds watch is just a convenient shortcut for:
  cds serve all --with-mocks --in-memory?

OPTIONS

  --port <number>

    Specify the port on which the launched server listens.
    If you specify '0', the server picks a random free port.
    Alternatively, specify the port using env variable PORT.

  --ext <extensions>

    Specify file extensions to watch for in a comma-separated list.
    Example: cds w --ext cds,json,js.

  --livereload <port | false>

    Specify the port for the livereload server. Defaults to '35729'.
    Disable it with value false.

  --open <url>

    Open the given URL (suffix) in the browser after starting.
    If none is given, the default application URL will be opened.

SEE ALSO

  cds serve --help for the different start options.

cds init/add ​

• Use cds init to create new projects
• Use cds add to gradually add facets to projects

cds env ​

Use cds env to inspect currently effective config settings

bookshop $ cds env get requires.db
{
  impl: '@sap/cds/libx/_runtime/sqlite/Service.js',
  credentials: { url: ':memory:' },
  kind: 'sqlite'
}

cds repl ​

Use cds repl to live-interact with Node.js APIs

bookshop $ cds repl
Welcome to cds repl v6.7.0
> SELECT.from(Foo)
Query {
  SELECT: { from: { ref: [ 'Foo' ] } }
}

> cds.requires.db
{
  impl: '@sap/cds/libx/_runtime/sqlite/Service.js',
  credentials: { url: ':memory:' },
  use: [Getter],
  kind: 'sqlite'
}

Debugging with cds watch ​

Start cds watch and enter debug. This restarts the application in debug mode. Similarly, debug-brk will start debug mode, but pause the application at the first line, so that you can debug bootstrap code.

If you do this in VS Code's integrated terminal with the 'Auto Attach' feature enabled, debugging starts right away. If you executed cds watch on a standalone terminal, you can still attach a Node.js debugger to the process.

For example:

• In VS Code, use the Debug: Attach to Node Process command.
• In Chrome browser, just open chrome://inspect and click Inspect.

Visual Studio Code ​

Install Visual Studio Code ​

1. Install Visual Studio Code and launch it.
2. Only for macOS: Install the code shell command.

Add CDS Editor ​

1. Go to Visual Studio Marketplace.
2. Choose Install and VS Code opens the details page for the extension SAP CDS language support.
3. In VS Code, choose Install to enable the extension.

Learn more about the CDS Editor.

Run Services ​

To run services, just open the Integrated Terminal in VS Code and use one of the cds serve variants, for example, use cds watch to automatically react on changes.

Alternatively, you can use the preconfigured tasks or launch configurations you get when creating a project with cds init. For example, in the Debug view launch cds run with the green arrow button:

Debug Services ​

You can add and stop at breakpoints in your service implementations. For example, add one to line 10 of our srv/cat-service.js by clicking in the gutter as shown here:

... then send the .../Books request again to stop there.

Restart the Server ​

Restart the server when you did changes to your code using the Debug views restart button:

Run a CAP Notebook ​

A CAP Notebook is a Custom Notebook in Visual Studio Code that serves you as a guide on how to create, navigate, and monitor CAP projects. With this approach, we want to encourage the CAP community to work with CAP in the same explorative manner that scientists work with their data, namely by:

• Visually interacting with their code
• Playing with REPL-type inputs (notebook input cells)
• Storing persistent code (notebook output cells)

The cell inputs/outputs are especially useful at later points in time when the project's details have long been forgotten. In addition, notebooks are a good way to share, compare, and also reproduce projects.

• If you are new to CAP Notebooks, try out the notebooks based on our documentation. When available for a given page, these are accessible via the "CAP Notebook button" on the right-hand-side of the screen and enable you to try things out on your local machine, for example the Getting Started in a Nutshell guide.

  

• To see which features are available in a CAP Notebook, open our CAP Notebook page: F1 → CDS: Open CAP Notebooks Page

• Magics, or magic commands, known from IPython are conventient functions to solve common problems. To see which line- and cell-magics can be used within a CAP Notebook, run a code cell with %quickref.

• Start an empty CAP Notebook by creating a *.capnb file.

Provided that the CDS Editor is installed, the CAP Notebook will be rendered automatically as the file is selected.

Eclipse ​

Prerequisites ​

• You have followed the instructions in Local Setup.
• You have installed Eclipse, Spring Tools, and our Eclipse plugin, see Add the SAP Cloud Business Application Tools for Eclipse.

Docker ​

Prerequisites ​

• You have installed Docker.

Build an Image ​

Create a file called Dockerfile and add this content for a quick setup:

FROM node:lts
# or use `FROM node:<NODEVERSION>` to match a specific Node version
# you have installed locally

USER node
ENV NPM_CONFIG_PREFIX=/home/node/.npm
ENV PATH=$NPM_CONFIG_PREFIX/bin:$PATH

RUN npm i -g @sap/cds-dk

FROM node:lts
# or use `FROM node:<NODEVERSION>` to match a specific Node version
# you have installed locally

USER node
ENV NPM_CONFIG_PREFIX=/home/node/.npm
ENV PATH=$NPM_CONFIG_PREFIX/bin:$PATH

RUN npm i -g @sap/cds-dk

Build your first image:

docker build -t cds .

docker build -t cds .

Run a Service in a Container ​

1. Run a container that is based on the image:

docker run --publish 4004:4004 -it cds sh

docker run --publish 4004:4004 -it cds sh

You see a $ command prompt from inside the container.

1. Move to the home directory:

cd

cd

1. Write a simple cds file:

echo 'service CatalogService { entity Books { key ID: UUID; } }' \
    > services.cds

echo 'service CatalogService { entity Books { key ID: UUID; } }' \
    > services.cds

1. Run the service:

cds run

cds run

1. Open http://localhost:4004 in a browser to test the application. You forwarded the port 4004 when running the container, which allows you to access the application as if it would run locally.

CDS Editors & LSP ​

The editor powered by the CDS language server implementation, provides source code validation including diagnostics, like error messages and warnings.

The following features are available for all editors based on our language server implementation for CDS in SAP Business Application Studio, Visual Studio Code, and Eclipse. The plugins are available for download for Visual Studio Code at Visual Studio Marketplace and for Eclipse at SAP Development Tools.

Short video about the SAP CDS language support extension for VS Code in action by DJ Adams.

Features and Functions ​

Syntax highlighting

Code completion

• Keywords
• Identifiers including not yet imported identifiers with corresponding using statement
• Using paths and artifacts including showing README.md documentation as details
• i18n translation IDs
• Turn on/off formatting regions

Where-used navigation

• Navigate to definitions
• Navigate to references
• Highlight occurrences

QuickFixes

• Create using statement for unknown artifacts.
• Maintain missing translation.
• Convert @cds.doc and @description annotations to doc comments.

Code formatting

Format...

• the whole document
• a selected range
• on-the-fly when completing statements using ; or }
• on save (depending on the IDE)
• on paste (depending on the IDE)

Use...

• many options, configurable using
  • settings file
  • command line switches
  • config UI with simulation of options for VS Code and Eclipse
  • JSON schema for textual support
• also for markdown in doc comments

Inventory (symbols)

• An inventory for the current file.
• An inventory for the workspace including query capabilities to select. For example, artifact types, names, also include reuse models.

Snippets for typical CDS language constructs

• Namespace and context
• using
• service
• type
• Entity and projections, ...
• Element, associations, and compositions
• Extend and annotate
• Annotations for documentation

With documentation extracts of capire explaining language concepts.

Hover information based on

• Doc comments
• @title, @description, and @cds.doc (deprecated) annotations
• Translations

Translation support

• Properties, JSON, and CSV files
• Navigate to translation definitions from translation IDs like '{i18n>customerName}'.
• Show translations on hover.
• Quickfix to maintain missing translations

And more

• Plugin framework for external handlers of annotation domains

Settings ​

Code formatting settings ​

These are settings coming with the CDS language server implementation. Use the command CDS: Show Formatting Options Configuration. You see the settings, grouped into three tabs: Alignment, Other, and Whitespace

Format on Type, Format on Paste, and Format on Save in VS Code ​

These are settings from the editor in VS Code:

1. Press F1
2. Open Preferences: Open User Settings
3. Filter for Format.
4. Tick the checkboxes to enable the settings.

Cds: Workspace Validation Mode ​

Default: ActiveEditorOnly

Keeps track of the active editor in focus. Only changes there are immediately validated.

The ActiveEditorOnly mode is especially useful in situations when navigating through a large model, that is having multiple files open (even if they are not shown as tabs) and editing a file that the others directly or indirectly depend on.

Cds > Contributions > Enablement: Odata* ​

Default: on

This setting enables extended support for annotations, that is refined diagnostics and code completion. Can be switched off for performance gains.

Cds > Workspace: ScanCsn ​

Default: off

Switch on to scan the workspace also for CSN files, additionally to CDS source files.

Note: CSN files are still considered if used from a CDS source file.

Cds > Quickfix: ImportArtifact ​

Default: off

Enable to get quickfix proposals for artifact names, like entities, that aren't imported via a using statement. For that, all definitions in the workspace need to be considered, which might be slow.

Commands ​

Welcome page ​

1. Press F1
2. Open CDS: Show CAP Release Notes

If there are new release notes, this page opens on startup. You can disable this behavior using the CDS > Release Notes: Show Automatically (cds.releaseNotes.showAutomatically) setting.

CAP Notebooks Page ​

1. Press F1
2. Open CDS: Open CAP Notebooks Page

This page provides information on all of features available in a CAP Notebook with a brief description and examples on each.

Beautify settings ​

1. Press F1
2. Open CDS: Show Formatting Options Configuration

Preview CDS sources ​

You want to create a preview of a specific .cds file in your project. You can do that using the command line. Here is how you do it in VS Code:

1. Open the file you want to preview.
2. Open the context menu.
3. Select Preview CDS source as... .
4. Choose the preview you want to see.

Visualize CDS file dependencies ​

Use the command from the context menu on a folder or CDS file.

A selection popup appears to choose one of three modes:

1. File to file (detailed)
2. File to file (reduced to folders)
3. Complete folder to complete folder

The first option shows every model file on its own. For very large models, the number of files and interdependencies may be too complex to be graphically shown. A message about insufficient memory will appear. In this case use the second option.

The second option reduces the graph by only showing the folders of all involved files and their interdependencies.

The third option always considers all files in a folder and their dependencies. This can be useful to understand architectural violations.

Example for architectural violation:
You want a clean layering in your project: app -> srv -> db. With this option, you can visualize and identify that there is a dependency from a file in the service layer to an annotation file in the application layer.

Hovering over a node will show the number of files involved and the combined size of all involved files. Use this function to get a rough understanding about the complexity and the compilation speed.

The command requires the third-party extension Graphviz (dot) language support for Visual Studio Code (joaompinto.vscode-graphviz). If you haven't installed it already, it will be suggested to install.

Editor Performance ​

With the following settings you can influence the performance of the editor:

Editor > Goto Location: Alternative Definition Command ​

Do not select goToReferences. Otherwise, being already on a definition often requires all models to be recompiled.

Workbench > Editor > Limit: Value ​

If open editors have using dependencies, a change in one editor will lead to a recompile of related editors. To decrease the impact on performance, lower the number.

Workbench > Editor > Limit: Enabled ​

To enable the limit value above, switch on.

Additional Hints to Increase Performance: ​

• Within SAP Business Application Studio: close CAP Data Models and Services view. Otherwise, it will ask for all workspace symbols at every change.
• Commands Go to References / Find All References will recompile all models that might have changed due to a change in a depending model. If there are index models, it often means that the complete workspace is being recompiled. Until a further change, reference calculation is reasonably fast.
• Command Go to Symbol in Workspace will recompile the complete workspace once, after that it is reasonable fast.
• Changing settings in CDS section will currently perform a complete workspace invalidation i.e. required indexes will lead to recompilations on demand as described above.
• Changing certain cds.env settings, for example folder configurations, will invalidate the workspace as well.

Command Line Client for CDS Code Formatter (beta) ​

The CDS code formatter provides a command line interface. Use it as a pre-commit hook or within your CI/CD pipeline, to guarantee a consistent formatting.

Installation ​

Install the CDS language server globally as a library via npm i -g @sap/cds-lsp. A new shell command format-cds is available.

Usage ​

Show help via format-cds -h. This explains all commands and formatting options in detail including the default value for each formatting option.

It is recommended to generate once for each project a settings file (.cdsprettier.json) with all default formatting options available. Execute format-cds --init in the project root. An existing file would not be overwritten. To adapt your settings to your preferred style, open the .cdsprettier.json file in VS Code. You get code completion and help for each option. There is also a settings UI in SAP CDS Language Support, reachable via command CDS: Show Formatting Options Configuration. This allows to see the effects of each formatting option on an editable sample source. Commit the .cdsprettier.json file into your version control system.

Use format-cds to format all your CDS source files. The effective set of formatting options is calculated in order of precedence:

• Default options
• Options from .cdsprettier.json file
• Command line formatting options

It is possible to have .cdsprettier.json files in subfolders. In this case the most relevant settings file per CDS source file is taken.

Use format-cds <foldername1> <foldername2> <filename> ... to restrict the set of CDS source files. By default, backup files with .bak file extension will be created.

Use -f switch to force an overwrite without creating a backup. This is on your own risk. Should there be problems data loss might occur, especially when formatting in a pre-commit hook. Better add .bak to your .gitignore file and not use -f.

CDS Lint & ESlint ​

To catch issues with CDS models and the CDS environment early, CAP provides an ESLint plugin with a set of recommended rules. Together with the lint client of the @sap/cds-dk, this comprises CDS Lint.

Usage via cds CLI ​

In your project's root folder, execute:

cds lint .

cds lint .

If there are no lint errors, there is no output. Otherwise, a standard ESLint error report will be printed.

Editor Integration ​

1. Download the standard ESLint extension for Visual Studio Code. CDS Lint seamlessly integrates with it. For SAP Business Application Studio this is preinstalled.

2. Configure our recommended rules for CDS model files in your project:

   sh

   cds add lint

   cds add lint

   This automatically adds the settings for the ESLint VS Code extension to the project's VS Code settings, installs the CDS ESLint plugin, and adds it to the ESLint configuration of your project.

CDS Lint Rules ​

The CDS Lint rules are a set of generic rules based on CAP best practices. The subset of these we consider most essential is part of the recommended configuration of the @sap/eslint-plugin-cds package.

Customization ​

Configuring CDS Lint Rules ​

Individual package rules can also be configured to be turned off or have a different severity. For example, if you want to turn off the recommended environment rule min-node-version, just add the following lines to your ESLint configuration file, shown here for type json:

{
  "rules": {
    "@sap/cds/min-node-version": 0
  }
}

{
  "rules": {
    "@sap/cds/min-node-version": 0
  }
}

Using the ESLint CLI ​

If you want to have more control over the linting process, you can access the CDS ESLint plugin natively via the ESLint CLI. To determine the proper command line options, it can help to refer to the DEBUG="lint" cds lint output, which shows all of the options and flags available.

For example:

Linting:
[lint] - eslint --ext ".cds,.csn,.csv" ...

SAP Business Application Studio ​

Set Up SAP Business Application Studio ​

If not already done, set up SAP Business Application Studio on SAP BTP.

Set Up Your Dev Space ​

1. Open the SAP BTP cockpit and choose SAP Business Application Studio from the Quick Tool Access section.

2. Choose Create Dev Space.

3. Provide a name for your dev space.

4. Choose Full Stack Cloud Application as the application type.

   By selecting Full Stack Cloud Application, your dev space comes with several extensions out of the box that you need to develop CAP applications. For example, CAP Tools, Java Tools, and MTA Tools are built in. This saves setup time. See Developer Guide for SAP Business Application Studio for more details.

5. Choose Create Dev Space.

   The creation of the dev space takes a while. You see that the status for your dev space changes from STARTING to RUNNING. See Dev Space Types for more details.

6. Once the dev space is running, choose the dev space by clicking on the dev space name.

   You're using a trial version. Any dev space that hasn't been running for 30 days will be deleted. See the full list of restrictions.

Features ​

To learn about the features specific to CAP development in the studio, see the guide Developing a CAP Application in SAP Business Application Studio

Tutorials Using SAP Business Application Studio ​

• Combine CAP with SAP HANA Cloud to Create Full-Stack Applications

• Set Up SAP Business Application Studio for Development.

• Video showing SAP Business Application Studio Productivity Tools