Chapter 2: Configuring the Bosque Environment

Now that we've learned what the Bosque project is and why it was developed, we are ready to see it in action.

In this chapter, we will learn how to configure a development environment to start experimenting with Bosque, and we will become familiar with the tools used to compile scripts and test our code. First, we will look at all the required prerequisites and how they can be fulfilled. Next, we will go through the installation process of Bosque itself. Eventually, we will write and compile our first Bosque "Hello, World" program.

Here is a list of the topics that we are going to cover:

  • Prerequisites for Bosque
  • Installing C++ compiler
  • Installing Bosque
  • Setting up the IDE for Bosque
  • Writing a "Hello, World!" program
  • ExeGen – Ahead-of-time Bosque compilation

By the end of this chapter, you will have a fully working Bosque environment, ready to write, compile, and run your own programs.

Technical requirements

All the specific requirements are mentioned and explained in the next section.

Prerequisites for Bosque

Before we can start using the Bosque language and experimenting with its features, we need to meet several requirements:

  • A 64-bit operating system
  • The LTS version of Node.js and NPM
  • TypeScript
  • A C++ compiler

At this point, you may wonder why we need Node.js and TypeScript in order to run Bosque programs. The answer is that the whole Bosque implementation is mostly written in TypeScript. The parser, type checker, interpreter, and command-line runner—all of these need to be built and transpiled into JavaScript before we can start using them.

Another thing that may seem a little bit confusing is the need for a C++ compiler to be installed on our system. The reason for this is that it is used for generating executable binaries from the Bosque source code. This is described in more detail in the next section. In this section, let's focus on the first three requirements.

64-bit operating system

This is something of a self-evident requirement, isn't it? At the same time, it's kind of strict—either you have 64-bit platform and you can run Bosque, or you don't and you can only see others playing with it. However, if you are in the group of those who have a 32-bit platform, there is still hope. It is possible that you have installed a 32-bit host OS, but your CPU is 64-bit. You can check this without installing any additional software. I will quickly show you how to do this on Windows, Linux, and macOS.

If you are certain that you are running a 64-bit operating system, you can skip this section and jump straight to The LTS version of Node.js and NPM section. The following description is intended for those who have installed a 32-bit OS, but are willing to check whether their CPU can handle 64-bit software, and if it does, then how to make use of it.

Windows

If you are using a Windows operating system, you need to open the Windows search box, type system information, and select the System Information option. On the right section of the window, look for the System Type element. If its value includes x86, this means that the CPU is 32-bit and unfortunately, there's not much you can do to run Bosque on your machine. However, if the value includes x64, then the CPU is 64-bit and there is a way for you to configure the Bosque environment.

Linux

For Linux users, the simplest way to check whether the CPU is 32-bit or 64-bit is to run the following command in the terminal:

$ lscpu

...

CPU op-mode(s):        32-bit, 64-bit

...

Look at the CPU op-mode(s) option. If the value includes 64-bit (as shown in the preceding code), this means that your CPU is capable of running 64-bit software and you can also run Bosque.

MacOS

If you are using macOS, then there is a bit more work to do. First, click the Apple icon in the menu bar and select the About This Mac option. In the window that appears, look for the More Info option and click it. Now, open the Hardware section and find the Processor Name attribute. At this point, you need to copy the name and consult the internet as to whether it's a 32-bit or 64-bit processor. If it's the latter, you are the happy owner of a CPU that can handle the Bosque language.

Virtual machine

This section is for those of you who have confirmed that their CPU can handle 64-bit software, but whose host OS is 32 bit.

The solution for you is to use a virtual machine. There is plenty of software supporting virtualization regardless of what operating system you use. The most common ones are VirtualBox, VMware, or Hyper-V. It is up to you which software to choose. Personally, I prefer VirtualBox. Thanks to virtualization, you can run any operating system you want on your host machine. This means that if your CPU is 64-bit, you can install a 64-bit operating system on a virtual machine and proceed with the installation of Bosque on the VM.

You should pick the virtualization software and an operating system of your preference and install it according to the official instructions available on manufacturer's website. We will not cover the installation steps in this book; we will focus on the direct Bosque dependencies instead.

Docker

Another way to install all of the requirements is to use Docker. It is a very convenient way because it wraps all of the prerequisites inside a container, and you can keep your system clean. However, keep in mind that you still need to have 64-bit CPU in order to run Bosque—you can't overcome this.

If you are using Windows, the minimum version required to install and run Docker is Windows 10 Professional or Enterprise. For macOS users, it is version 10.14 or newer.

You need to install Docker Desktop and Visual Studio Code Remote Development Extension Pack, or you can manually use Docker image and run it. All of the required instructions can be found in the Bosque GitHub repository at https://github.com/microsoft/BosqueLanguage/blob/master/docs/extras/docker.md. As with the virtual machine method, we will not cover the Docker installation steps in this book, as we want to focus on the direct Bosque dependencies. However, if you decide to use Docker and succeed, you can skip the next few sections and jump straight into the Setting up the IDE for Bosque section.

The LTS version of Node.js and NPM

Now that we are sure that we have 64-bit operating system installed, we can focus on the next requirement, which is Node.js and NPM. As previously stated, the Bosque implementation is mostly written in TypeScript. In order to run it, we need the Node.js runtime.

You can check whether you have it installed on your system by opening your favorite terminal and typing the following commands:

$ node -v

$ npm -v

At the time of writing, the LTS version of Node.js is 14.16.1, which includes NPM 6.14.12. If any of these commands failed, it means that you don't have all the required software installed. In that case, you should continue reading this section. However, if you confirmed that you have installed Node.js and NPM by running these commands, you can skip this section.

Installing Node.js is pretty straightforward. The next sections will show you how to install Node.js and NPM on various operating systems.

Windows

In order to get Node.js and NPM on a Windows machine, go to the official website at https://nodejs.org/ and download the LTS version that is recommended for most users. Once the installer is downloaded, run it and proceed with the instructions shown in the installer window. You will be asked to accept the license agreement and choose the destination folder and components that you wish to install. If you are not sure what to select, you can safely click on Next at each step and then click on Install at the end. After a while, you should see a dialog box stating that Node.js has been successfully installed. You just need to click on the Finish button and that's it—you have everything ready to proceed to the next section. The following screenshot shows the final window, showing a successful installation of Node.js:

Figure 2.1 – Successfully installed Node.js

Figure 2.1 – Successfully installed Node.js

Linux and MacOS

The installation of Node.js on Linux or macOS machines is as simple as it is on Windows. You can go to the official website at https://nodejs.org/ and download the installer file that will be automatically selected for your platform. However, I recommend a slightly different approach. There are situations where you need to use a different version of your runtime to test some features. For example, you might need to check whether your NPM module will work with some older versions of Node.js. Managing multiple versions of Node.js may be problematic when you have one global version installed and need to replace it with an older one for a short time. This is why we have tools such as Node Version Manager (NVM) available; it allows us to maintain multiple versions of Node.js simultaneously and switch between them at any time. I strongly recommend using it whenever possible.

To install NVM, you need to run the installation script. You can do it in a few ways, but I will only show you one. Open your favorite terminal and run the following command:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.36.0/install.sh | bash

This will download the installation script and run it immediately. Once this is done, you need to close and reopen the terminal window. Note that the version in the link may vary depending on when you are reading this book. At the time of writing, the latest one is v0.36.0.

Now we can install the LTS version of Node.js by running the following command:

$ nvm install --lts

Once this command finishes, you should have all the required components installed. You can verify this by running these commands again:

$ node -v

v14.16.1

$ npm -v

6.14.12

You should see the versions of Node.js and NPM installed on your system respectively, as shown under the preceding commands.

TypeScript

We are halfway through. The next thing we need to do is to install TypeScript, which is the main language used to implement Bosque.

In order to verify whether you have already installed it, you can run the following command in any terminal regardless of your operating system:

$ tsc –v

Version 3.4.5

If the output shows a version number (as shown in the preceding code under the command), it means that you can skip this section; otherwise, you need to install TypeScript on your machine.

The installation of TypeScript is the same for Windows, Linux, and MacOS, and it comes down to running only one command:

$ npm install -g typescript

After the installation process completes, you will be able to use the tsc command. You can verify this by running the following command again:

$ tsc -v

You should see the version of TypeScript installed on your machine.

Installing a C++ compiler

After fulfilling the prerequisites, it is time to install a C++ compiler. This component is required for generating executable binaries from the Bosque source code. It is described in more detail later on in this chapter. By default, Bosque tools expect the Clang compiler on Windows, Linux, and macOS, but if you wish to use a different one, or if you already have a C++ compiler installed on your system, this is also fine. If this is the case, you can skip this section completely and jump straight into the Installing Bosque section.

Important note

If you choose not to use the default Clang compiler, you will have to add the --compiler option when compiling programs using the exegen command. It is described at the end of the chapter, in the ExeGen – Ahead-of-time Bosque compilation section.

In order to install the Clang compiler, you should install something called LLVM. This is a collection of components that are used to optimize and generate machine code. This library allows us to use any of its modules to build compilers or other software connected with programming languages. One of its components is Clang. This means that by installing LLVM, you automatically install Clang with all other required software.

I will quickly describe the installation process of Clang on various operating systems.

Before we start, it is worth checking whether you have already installed Clang on your machine. In order to do this, you need to run the following command in the terminal:

$ clang --help

If it fails, this means that installation is required. However, if this command outputs help information, then you can skip this section and jump straight into the Installing Bosque section.

Windows

Installation of LLVM on Windows is pretty simple. You need to visit the official download page at https://llvm.org/builds/ and find the Windows installer (64-bit) link in the Windows snapshot builds section. Clicking on this link should start the download. After the installer is downloaded, you should run it and proceed with the instructions shown on the screen. At the end of the installation process, you should see the following screen:

Figure 2.2 – Successfully installed LLVM

Figure 2.2 – Successfully installed LLVM

This process should result in the Clang compiler being installed on your machine, ready to work. To verify whether everything went fine, you can run the previous command again and see whether you can see the help information.

Linux

There are a few ways to get Clang on Linux, depending on your distribution.

For Ubuntu or Debian distributions, you can visit the download page at https://apt.llvm.org/ and follow the installation steps described there.

If you are using other Linux versions, you can visit a different download page at https://releases.llvm.org/download.html and select the correct installer depending on your distribution.

The last way requires a little bit more work. If the previous methods do not work for you, this one most likely will. You need to manually clone the LLVM project repository and build it. All of the required steps are described on the official website at https://clang.llvm.org/get_started.html in the Building Clang and Working with the Code | On Unix-like Systems section.

After completing all the steps, you should have the Clang compiler installed on your machine and verified.

MacOS

If you are a user of macOS, then you should be happy. The installation of LLVM on your operating system is very simple. The only thing you need to do is open the terminal and run the following command:

$ brew install llvm

This command will print a lot of output messages indicating the installation of all the dependencies. If no error:, fatal:, or Error: messages were shown, it means that the command succeeded, and once it's done, you should be able to use Clang on your system. Simple, isn't it?

This was the last component that Bosque needs to run properly. If you have persevered up to this point, you should be proud of yourself. The hardest part is done. All the requirements are met and we can jump straight to the key element of our journey—Bosque.

Installing Bosque

Finally, it is time to install the Bosque language itself. The source code of the Bosque language is available on GitHub. This is the place where we must download the source files from. We can do this in two ways:

Both ways are equally effective, so you can go with the one that suits you better. We, however, will focus on the second way as it is simpler and faster.

The first thing to do is to open any terminal in a location of your choice and run the following command:

$ git clone [email protected]:microsoft/BosqueLanguage.git

Keep in mind that the location that you have chosen is the one where the Bosque language is going to be installed.

Now, go into the ./BosqueLanguage/impl/ directory that was just created:

$ cd BosqueLanguage/impl/

This directory consists of the whole Bosque implementation. There are a lot of files and directories that define things such as parser, interpreter, type checker, and more. As you have probably guessed, some external libraries and modules have been used to implement all of these things. So let's install them by running the following command:

$ npm install

This command may take a while, depending on your internet connection speed:

Figure 2.3 – Successfully installed Bosque dependencies

Figure 2.3 – Successfully installed Bosque dependencies

Once the dependencies are installed, you are ready to build the sources. In order to do this, you need to run the following command:

$ npm run build

In fact, this command is not necessary to run. This is because, at the time of writing, the next two commands are internally doing the same thing, plus some extra stuff, such as testing or creating an alias. However, I recommend running this command on its own because the definition of the test and make-exe scripts may change in the future, and running the build script may become necessary. Nonetheless, if you don't want to run this script, you can jump straight to the test or even make-exe scripts, as they will do the same thing.

Once the build process is over, it is a good idea to run tests so we can be sure that everything was installed correctly and works fine. You can do this by running the following:

$ npm test

This will take a few minutes to complete, so if you don't want to wait that long, you can skip this step. However, it is recommended that you do so, as you can ensure that Bosque was installed correctly, so you will be certain that potential future errors are not caused by failed installation. This command will throw a lot of output messages showing which test suite is currently in progress. If everything goes well, you should see a message similar to the following at the end:

All 6 test suites passed!

The last step is to run the following command:

$ npm run make-exe

This command will create an alias for compiling Bosque programs into executable binaries. If you see something like this at the end of the output, it means that the command succeeded:

[...] pmexegen -> [...] pm ode_modulesosque-reference-implementationin untimesexegenexegen.js

[...] pm ode_modulesosque-reference-implementation -> [...]BosqueLanguageimpl

To verify that the alias is created, you can run the following command:

$ exegen --help

If you see some help information, this means that the alias has been created successfully.

At this point, you should have installed the Bosque language on your system. Congratulations!

In fact, you could start writing Bosque programs right away—which you can do, if you want—but I strongly recommend that you prepare yourself a bit better by installing an IDE that supports the Bosque syntax; it will make it a lot easier to write and understand the code.

Setting up the IDE for Bosque

This section covers the installation process of the Visual Studio Code (VSC) extension that supports the Bosque language. Because the language itself is very new, there are not many advanced solutions supporting it yet, so the existing extension to VSC comes directly from the Bosque creators and is currently limited to syntax and brace highlighting only. Nonetheless, it makes the code much more readable.

You probably know this IDE already; it's one of the most popular code editors out there. It's free to use and has a rich set of extensions that—when organized well—can create a really powerful IDE. The installation process is pretty straightforward, so we will not go through this step by step. If you don't have VSC installed yet, all you need to do is go to the official website at https://code.visualstudio.com/download/, download the installer, and run it.

After the installation completes, you can install the Bosque language extension. In order to do this, you need to copy the ./bosque-language-tools/ directory directly into the ./extensions/directory. I'll show you how to achieve this depending on your OS.

Windows

The simplest way to install the extension on Windows is to open two Explorer windows. In one Explorer window, navigate to the directory in which you have installed the Bosque language. In the other, navigate to the location where VSC has been installed. The location path should look similar to this one:

C:UserskaczmAppDataLocalProgramsMicrosoft VS Code

Once you have both of the windows opened in the right locations, you need to copy the .osque-language-tools directory from the first window (the one with the Bosque installation) to the . esourcesappextensions directory in the second window (the one with the VSC installation).

Now, you need to restart the VSC editor, if you have it opened already.

Linux and MacOS

If you are using Linux or macOS, you can do this by opening your favorite terminal in the location where you have installed the Bosque language and typing the following command:

$ cp -r ./bosque-language-tools ~/.vscode/extensions/

This will recursively copy the directory with all of the subdirectories in the desired target location.

After this, you need to restart the editor, if you have it running.

This is it: you have installed the VSC extension that supports the Bosque syntax. To test whether everything works fine, let's write our first Bosque program and see whether the syntax is highlighted properly and the program will compile without any errors.

Writing a "Hello, World!" program

First things first: let's create a folder for our first program. You can do this directly from VSC or by using your favorite terminal. Since we have just set up our IDE to play with Bosque, I recommend that you use it. First, click File | New File. A new tab named Untitled-1 should appear—click File | Save (or press Ctrl + S on the keyboard) in order to rename it and save it at your desired location. Save the file under the name main.bsq. If you prefer to do this using a terminal, open it and type the following command:

$ mkdir first-project

$ cd first-project

Now, open VSC in the directory you have just created and create a file named main.bsq, as described earlier.

Once you have created the main.bsq file, fill it with the following content and save it:

namespace NSMain;

entrypoint function main(): String {

        return "Hello, world!";

}

I will explain this code in a second. For now, just write the preceding code and save the file.

After this, run the following command:

$ exegen main.bsq

This command runs the Bosque compiler, which creates an executable file. Depending on your OS, it will be a.exe or a.out. As you may already have guessed, the first one is created on Windows while the second one is on Linux and macOS.

Let's run it and see how it works. On Windows, you just need to run the following command:

$ .a.exe

On Linux and macOS, the following command should work:

$ ./a.out

If you encounter an error with the permissions, saying bash: ./a.out: Permission denied, try to run the following command first:

$ chmod +x a.out

After running the executable file, you should see the "Hello, world!" text on your screen, as shown in the following screenshot:

Figure 2.4 – Output of the "Hello, world!" program

Figure 2.4 – Output of the "Hello, world!" program

You may have expected that the output would not contain enclosing quotes. In Bosque, strings are printed with quotes—it is an intentional implementation. We won't dive into the Bosque internals to show this because that wouldn't bring much benefit, so you must just trust me on that when I say this is how it's been implemented.

At this point, you have learned how to compile and run Bosque programs. It's a big step forward. Congratulations!

Now, let's get back to the code you have written and see what happens there in more detail.

Understanding the code

Let's break down this code line by line.

Look at the first line:

namespace NSMain;

If you are familiar with languages such as C++ or C#, then you probably know already what namespaces are. Nonetheless, let's remind ourselves what they are.

A namespace is kind of a bag for your functions, variables, and so on. Normally, you cannot have two functions with the same name defined in the same scope. Usually, it's treated as a compile-time error and your program won't be even compiled. A namespace allows us to wrap these two functions into different groups so that they won't collide anymore. Basically, they enable us to achieve a better code separation.

In Bosque, you must declare a namespace. Without any namespace declaration, the program won't even compile. NSMain is a default namespace, which the ExeGen tool is looking for during compilation. You can change it using the --entrypoint (-e) parameter, which I will talk about in the next section.

The second line looks like this:

entrypoint function main(): String {

Here, we have two main things to look at. The first one is the entrypoint keyword. As the name suggests, it tells Bosque that this is the main entry point of the program that the whole execution will start from. More on this is explained in Chapter 4, Entrypoint Function. At this point, it's important to know that you must have at least one entrypoint function in your program.

The second thing is the function main(): String part of the code. This line defines a function called main without any parameters and with the return type String. The syntax is very similar to TypeScript, where we define types after a colon. You must provide a return type for the entrypoint function, otherwise, you'll get an error.

The third line consists of the following code:

return "Hello, world!";

This simply states that the function should return the provided text. Since we have specified the return type of the main function as String, we must return a string. If you change this value to something else—for example, a number—then the program won't compile. One more important thing to notice is the semicolon at the end of the line. In Bosque, you must put semicolons at the ends of lines—they are required and work in the same way as they do in other popular programming languages, such as C++.

And that is it. Now, you understand the code of your first program and know what is going on. I strongly recommend that you play with this code a little bit. Try to return different types of values and see the output. This way, you will get used to the process of compilation and running the executables, and will familiarize yourself with the errors that are thrown in various scenarios.

ExeGen – Ahead-of-time Bosque compilation

I have mentioned the ExeGen tool a few times before. It's time to take a closer look at this in more detail to see how it works and how to use it.

Remember when you ran the following command during Bosque installation?

$ npm run make-exe

This command creates the exegen alias command, which runs the ExeGen tool with the provided parameters. We will go through the supported list of parameters with an explanation of what they do, but first, let's clarify what this program is and how it works.

Basically, ExeGen is a simple command-line tool that takes a .bsq file as an input and produces an executable binary as an output. Its internal logic is a bit more complex than it sounds, though. Roughly speaking, the tool first generates an assembly from an input .bsq file. Then, it emits a C++ code based on the preprocessed assembly. In the end, it runs a C++ compiler that produces an executable binary.

Such a compilation process has a few advantages. One of them is that it allows Bosque programs to start up really fast. Having an executable binary helps a lot, in this case. Another advantage is that during the C++ code emitting phase, you can optimize the code so that it will be even faster (for example, by precompiling some logic directly into constant values, speeding up the startup.

Parameters for ExeGen

The ExeGen tool takes a list of parameters. We will go through all of them, as the list is not very long:

  • -e, --entrypoint [entrypoint]: When you were writing your first program, you created an entrypoint function. You named it main and everything was working fine. If you tried to change this name to something else and tried to compile your program, it wouldn't work. The same applies to the namespace you created—if you tried to change it to something else, the compiler would throw an error. This is because the default entry point that ExeGen is looking for is NSMain::main. In order to change this, you can pass the -e parameter to ExeGen and provide your entry point name. For example:

    $ exegen main.bsq -e "NSCustom::start"

  • -o, --outfile [name]: You have probably noticed that every time you used ExeGen so far, it has produced an a.exe or a.out file. Let's be honest—it's not the best name for your program executable, and changing it after every compilation can be frustrating. Fortunately, you can specify the name using the -o parameter. For example:

    $ exegen main.bsq -o main.exe

    This will produce a main.exe file instead of the a.exe.

  • -c, --compiler [compiler]: Back in the Installing C++ compiler section, I said that by default, Bosque expects the Clang compiler, but you can install another one if you wish. And that's true. However, if you don't use the default compiler, you need to specify it when using ExeGen by using the -c option. For example, if you are using GCC compiler, you can specify it like this:

    $ exegen main.bsq -c gcc

  • -l, --level [level]: This option lets you specify the compiler build level. By default, it's set to debug, which means that all asserts/pre/post/invariant checks are enabled, debugging messages are produced, and no optimization is done. There are two more options: test, which enables only test and release checks, still produces debug messages, and performs light optimization; and release, which enables only release checks, disables all debug messages, and performs platform-specific optimization. You can change the compiler build level like this:

    $ exegen main.bsq -l release

  • -f, --flags [flags]: This option allows you to pass additional flags to the C++ compiler of your choice. For example, if you are using the GCC compiler and you wish to print all warning messages, you can pass an additional flag to the compiler:

    $ exegen main.bsq -c gcc -f "-Wall"

At the time of writing, these are all the parameters that are supported by the ExeGen tool. Keep in mind that you can use multiple parameters at once. If you are using the default compiler and entrypoint function, generally, you will probably be using only the -o option, so the executables' names won't collide. For production builds, you'll want to use the -l option to set the compiler build level to release.

Alright, so in this section, you learned about what the ExeGen tool is, how it works, and how you can customize its behavior. This knowledge may become useful later on in this book, as well as in your own experiments.

Now it's time to summarize this chapter.

Summary

You've learned a lot so far. This chapter has taught you a lot of practical things that are crucial when getting started with Bosque. Let's do a short recap of what you've learned.

First, we talked about the software requirements to run Bosque. We covered the required OS architecture and what you can do if your host system does not meet the requirements. After that, you learned what additional software is mandatory in order to install and run Bosque.

Then, we covered the compiler—why it is needed and how to install it. You learned about the default Bosque compiler, which is used to generate executables, and how you can install it on Windows, Linux, and macOS.

You then installed the Bosque language itself, along with the tools such as ExeGen. You also learned what the recommended IDE for Bosque is, and how you can install the syntax highlighter so that writing Bosque programs is much easier.

The next big thing that you looked at was your first Bosque program. We wrote a simple "Hello, World!" program and compiled it. Then, we went through the code line by line and looked at what was going on there. You learned about the required namespace and the entrypoint function and what types of values it can return.

Finally, we took a closer look at the ExeGen tool, which is responsible for producing executable binaries from our Bosque programs. We talked a little bit about how the tool works internally and what's good about that. In the end, you learned what parameters are accepted by the tool and how you can customize its behavior.

Now you are ready to jump into the Bosque language features. In the next chapter, we will cover the key features of the language and what they do. We will also compare them to some popular languages so it will be easier to see the advantages of Bosque.

Questions

  1. What is the default C++ compiler that Bosque uses?
  2. Which tool generates executable binaries from the Bosque source code?
  3. What is the keyword that must be added to the main function of the Bosque program?
  4. Are semicolons a must in Bosque programs?
  5. How can you change the default namespace and main function name and compile your programs without errors?
  6. What would happen if you changed the main function name from main() to Main() and tried to compile the program again?

Further reading

Here are the links to some useful resources related to Bosque environment configuration:

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.133.121.160