At the end of this exercise, you'll have a comfortable command line environment within which to work, and the btp CLI installed and ready to invoke.
Your activities in this CodeJam will be predominantly on the command line. And the key to a successful and enjoyable CodeJam include a working environment that is consistent for everyone.
To enable this, we use the SAP Business Application Studio (App Studio), a cloud based interactive development environment (IDE) that, amongst many other features, gives us all a command line based on the Bash shell, in a UNIX (Linux) environment - by far the most widely used in today's era of cloud native.
🐳 As an experimental alternative to this, we have a container based approach that - if you're brave and willing to try it out - you can use instead. It assumes you have Docker Desktop installed, as described in the Docker Desktop section of the Prerequisites document. So if you want to use a container for this CodeJam, jump over to the container directory and follow the instructions to get set up. And then come back here, and jump forward to the Install the btp CLI section below.
Why a Dev Space in App Studio, and why a Basic one at that? Well, because it allows everyone to have the same environment, so we can all learn at the same pace and experience the same things. Moreover, App Studio Dev Spaces offer a VS Code like experience. In fact, as of November 2022 it's now powered by Code OSS with a file explorer, version control interface, comfortable tabbed editor environment, and - most importantly for us - a modern terminal emulator.
The power of the btp CLI comes from multiple angles:
- it gives us comfortable and convenient access to the BTP APIs
- it is a command line tool, meaning it lets us stay within our development flow and can be combined with other developer and devops tools
- it is scriptable - we can make use of the btp CLI within shell scripts to create whatever automation we need relating to management of resources on BTP
App Studio Dev Spaces, even Basic ones, give us that essential command line context. So that's what we're using. By all means, after this session, feel free to install and use the btp CLI where it makes sense for you.
You should have already set up a Dev Space when working through the prerequisites to this CodeJam. If you need a quick reminder of how to get to the SAP Business Application Studio and your Dev Space, you can pop over to the SAP Business Application Studio section of the prerequisites to see where to go.
Initially the Dev Space will look something like this:
This is lovely, but we want to focus on the command line, so let's remove everything to make as much space as possible for that command line.
You can access all the menu commands via the
☰symbol in the top left.
👉 Do the following:
- close the Get Started tab with the
x(optionally having checked the "Don't show this page again" checkbox at the bottom) - ensure the Explorer is closed (on startup it is likely already closed, but if it isn't, you can toggle it between the closed and open state by using the "Explorer" button which is the first one depicting two documents directly below the
☰symbol in the column on the far left) - open up a terminal session with menu path
Terminal -> New Terminal - optionally, open the Settings with menu path
File -> Preferences -> Settings, find the font size setting for the terminal ("Terminal › Integrated: Font Size"), within Features / Terminal, and adjust as appropriate; close the Settings tab when you're done with this - drag the horizontal line up towards the top of the screen to give you maximum terminal space, or use the Maximize Panel Size button (the
^symbol) on right of the terminal shown in the screenshot below
Notice that in the menu items you're shown keyboard shortcuts for some of the actions you're carrying out (e.g. opening a new terminal, or opening the preferences) - these can make the use of the Dev Space even more comfortable.
You should end up with your Dev Space looking more like this:
All set!
The btp CLI tool is available from the SAP Development Tools website, specifically in the Cloud section.
The basic way to install it is as described there - go to the page, work out which tarball to download, download it, expand and unpack it, extracting the executable into a place that you decide. You want it in a place that will be searched when you invoke it directly.
As a user in the terminal within the Dev Space, we don't have administrative access to be able to create files or directories except within our user space. So let's decide to put the executable in a bin/ directory within our home directory, and add that directory name to the PATH environment variable so that we can run it without specifying the full path.
So at this stage you have a choice.
- you could follow the instructions on the download page, choosing the
bin/directory (i.e.$HOME/bin/which resolves to/home/user/bin/in the context of the Dev Space terminal session) - or you could use the
getbtpcliscript to do this for you, a script that will let you discover and download the latest versions as they become available
👉 In this exercise, follow the second approach and use the getbtpcli script.
If you do choose this approach, make sure you end up with
/home/user/bin/btp
as an executable file.
This script is part of an SAP Tech Bytes topic, specifically SAP btp CLI, and is available in the corresponding branch: getbtpcli.
👉 Make sure you're in your home directory:
cd $HOME👉 Download the getbtpcli script and make it executable:
curl \
--remote-name \
--location \
--url "https://raw.githubusercontent.com/SAP-samples/sap-tech-bytes/2021-09-01-btp-cli/getbtpcli" \
&& chmod +x getbtpcliThe
getbtpcliscript itself will be placed in whatever directory you happen to be in, which will be your home directory, which is fine. So you'll need to specify the relative path to it when running it, like this:./getbtpcli(because your home directory is traditionally not included in the list of directories in yourPATHenvironment variable).
👉 Run the script with the test mode option just to check what the latest version of the btp CLI is (the output will be something like "Version is 2.61.0"):
./getbtpcli --testIf you're going off piste and carrying out these exercises on macOS, please note that you'll need to have the "proper" GNU version of
grepinstalled (see this Stack Overflow entry for tips, especially the part about "needing to use these commands with their normal names"). Otherwise you may encounter errors. If you're running on a Windows based machine, then I'm afraid I can't help you, except perhaps to suggest using the Windows Subsystem for Linux :-)
👉 Run the script, to download, unpack and install the btp CLI:
./getbtpcliHere's an example session where it's run in test mode first and then for real:
user: user $ ./getbtpcli --test
Version is 2.61.0
user: user $ ./getbtpcli
Proceed (with Enter) only if you accept the SAP Developer Licence 3.2
(see https://tools.hana.ondemand.com/developer-license-3_2.txt) ...
Version is 2.61.0
user: user $
Over the course of the next couple of exercises you'll be appending various setup commands to your $HOME/.bashrc file. The contents of this file are executed each time you start a new shell, which for example, in the case of your Dev Space in the App Studio, is every time you open up a new terminal. Rather than have to close and open up a new terminal for new commands in $HOME/.bashrc to take effect, you can add an alias that you can call instead, which will execute the last line of the file in the context of your current shell session.
👉 In what you're about to do, it's important that you don't accidentally clobber your entire .bashrc file, so first take a copy of it:
cp $HOME/.bashrc /tmp/👉 Now add a line to the end, which defines the alias - if you're typing it in manually, first, well done, and second, make sure you use the command as shown here, with the single quotes (inside the double quotes) and using the append redirection which is a double greater-than sign >>, and not a single one:
echo "alias bu='source <(tail -1 $HOME/.bashrc)'" >> $HOME/.bashrcThe alias is named bu for "Bash Update" (you can use a different name if you prefer).
👉 Now, in a sort of bootstrapping process, run this actual command once:
source <(tail -1 $HOME/.bashrc)This will take the last line of your $HOME/.bashrc (the line you've just added) and run it in the context of your current shell session (see the Further reading section on what source is and does). Yes, this does feel a bit meta. Which is a bonus!
👉 Check that you have this new bu alias like this:
aliasYou should see a list including the one you've just indirectly defined in your current shell, which should look like this:
alias bu='source <(tail -1 /home/user/.bashrc)'
You should now have the btp CLI available in your $HOME/bin/ directory.
👉 Take a look:
ls -l $HOME/bin/You should see something similar to this:
lrwxrwxrwx 1 user user 10 Jan 3 15:26 btp -> btp-2.61.0
-rwxr-xr-x 1 user user 11749335 Nov 16 11:41 btp-2.61.0
Before you can run the btp CLI simply as btp you need to add that bin/ directory to your PATH environment variable. To make this addition persistent, let's add it to $HOME/.bashrc.
👉 Append a line to the .bashrc file in your home directory which adds the bin/ directory to the PATH environment variable
echo 'export PATH=$PATH:$HOME/bin' >> $HOME/.bashrc👉 Now run the bu alias to have that export invoked in your current shell's context:
bu👉 Check that the addition of your $HOME/bin/ directory to the PATH environment variable has taken effect, as follows (you should see it at the end):
echo $PATHHere's an example of what you should see:
user: user $ echo $PATH
/home/user/.node_modules_global/bin:/extbin/bin:/extbin/npm/docker/bin:/extbin/npm/globals/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/curl/bin:/home/user/bin
user: user $You can also make life easier for yourself with shell parameter expansion and have each of the individual locations displayed on separate lines. Here's an example of that:
user: user $ echo -e ${PATH//:/\\\n}
/home/user/.node_modules_global/bin
/extbin/bin
/extbin/npm/docker/bin
/extbin/npm/globals/bin
/usr/local/sbin
/usr/local/bin
/usr/sbin
/usr/bin
/sbin
/bin
/curl/bin
/home/user/bin
user: user $Depending on whether you're in a Dev Space terminal or in a container, the actual paths shown in the list may differ.
You can of course just check if btp can be found, for example:
user: user $ which btp
/home/user/bin/btpNow you can invoke btp with confidence from wherever you are, and in all future terminal sessions in your Dev Space.
👉 Try it now:
btpYou should see something like this:
SAP BTP command line interface (client v2.64.0)
Usage: btp [OPTIONS] ACTION GROUP/OBJECT PARAMS
CLI server URL: https://cli.btp.cloud.sap (server v2.72.0)
Configuration: /home/user/.config/.btp/config.json
You are currently not logged in.
Tips:
To log in to a global account of SAP BTP, use 'btp login'. For help on login, use 'btp help login'.
To provide feedback about the btp CLI, use 'btp feedback' to open our survey.
To display general help, use 'btp help'.
👉 While you're here, take a few moments to stare at this line, to get a feel for btp CLI invocations on the command line:
Usage: btp [OPTIONS] ACTION GROUP/OBJECT PARAMS
You'll find that it helps to remember this invocation format, by considering that -- usually -- the GROUP is plural, and the OBJECT is singular. For example, in the next exercise, you'll use btp list accounts/subaccount.
There's an SAP Help topic page linked in the Further reading section that explains how this is structured.
At this point you have the btp CLI set up and ready to invoke from the command line.
- SAP Tech Bytes: btp CLI – installation
- SAP Help topic Command Syntax of the btp CLI
- Bash shell parameter expansion
- The source builtin in Bash (Sourcing a File is also a good resource)
If you finish earlier than your fellow participants, you might like to ponder these questions. There isn't always a single correct answer and there are no prizes - they're just to give you something else to think about.
- Expressing the individual locations within your
PATHon separate lines was done using Bash shell parameter expansion. Using other command line tools, how else might you do it? - Is placing the
btpexecutable within$HOME/bin/a good option? Will it still be there if you restart your Dev Space? - What help is available for the btp CLI on the command line? What does
btp helpshow you? - Why are there two entries in
$HOME/bin/for thebtpexecutable?