Introduction

Introduction


NSLink is NumScale's linker. This linker requires an underlying traditional linker in order to link C/C++ file objects. It supports its own set of options which may be used to customize the way the linker will be invoked.

Note
To be able to use NumScale's libraries or products, you MUST use NSLink.

Using Makefile(s)


NSLink can easily be integrated into a bare Makefile. A standard Makefile uses specific macros when it comes to link object files. The important variable here is LD. The following example shows a minimalist Makefile using NSLink as the linker.

Note
You can use both LFLAGS and LDFLAGS or even other variables. You just have to make sure that NSLink's options are passed while compiling.
## Minimal working example using Makefile(s)
## ---------------------------------------------------------------------------------------------
LD = nslink-x86_64
LDFLAGS += -nslink:target:x86_64
LDFLAGS += -L/opt/bsimd/lib
LDFLAGS += -lbsimd

CXX = g++
CXXFLAGS += -std=c++11

all: nslinked

nslinked: nslinked.o
    $(LD) $(LDFLAGS) $< -o $@

%.o: %.cpp
    $(CXX) $(CXXFLAGS) -c $< -o $@
Warning

Beware of copy-pasting here, Makefile requires tabulations for rules.

You may have the following error if you have spaces instead:

Makefile:14: *** target pattern contains no '%'. Stop.

Here is the basic file nslinked.cpp:

#include <iostream>
int main()
{
std::cout << "I have been linked using NSLink!" << std::endl;
return 0;
}

Using make command will give you the following output:

g++ -std=c++11 -c nslinked.cpp -o nslinked.o
nslink-x86_64  nslinked.o -o nslinked
NumScale Linker version 1.0 for x86, amd64, arm, aarch64, ppc64, ppc64le.
NumScale SAS. All rights reserved.

Using Visual Studio


Note
The following tutorial is using Microsoft Visual Studio 2015

NSLink may easily be used by Microsoft Visual Studio with only few configuration steps. NSLink comes with a ready-to-use configuration file for VS that automatically changes the IDE linker. These configuration files are known as Property Sheet.

While linking, VS is looking for some special user-macros in order to use a different linker to the default one:

  • ToolLinkPath
  • ToolLinkExe

The following tutorial explains how to setup NSLink configuration using the IDE. It also assumes that your project is already a VS solution and that you are familiar with the IDE user interface.

In order to use Property Sheet features, you must first enable it.

Enable Property Manager

Now you must select the Property Manager panel.

Go to Property Manager tab

To use NSLink configuration, you must add an existing Property Sheet. You may Browse and search for the file named NSLink.props under the NSLink installed folder (C:\Programs Files (x86)\NumScale\NSLink).

Note
You must repeat this step for each of your solution's configurations in order to use NSLink for each of them.
Add Existing Propery Sheet

You should now see an additional line named NSLink right under your selected configuration.

Double-clicking this new line will open a new window that shows each user-defined-macro that will be used by the IDE.

NSLink User Macros

NSLink Property Sheet uses some user-macros so that you need not add all of NSLink's arguments to the linker command-line. Let us add a new Property Sheet to your selected configuration. A good name for it would be NSLinkOptions.props but any other name may be used.

Add New Project Property Sheet

This will open the following window that you have already seen if double-clicked your NSLink Property Sheet.

Add New Project Property Sheet - window

You can now add your own macros and customize NSLink arguments. Currently only two user-macros are used by the default configuration:

  • NSLinkTarget: which defines the target architecture
  • NSLinkFlags: for all other NSLink options
Note
For the full options list, please refer you to the following link.

Here is an example of what your freshly added Property Sheet should look like:

NSLinkOptions User Macros

To ensure that Microsoft Visual Studio is using NSLink as its linker, you may omit the /NSLINK:nologo option from the NSLinkFlags user-macro and start a build. Select the Output panel from the middle screen. You should now see the NSLink logo as shown in the red-box in the following screen:

NSLink Logo

Using XCode


Note
The following tutorial is using XCode 7.2.1

Integrating NSLink to XCode is quite straightforward using .xcconfig files. As with Microsoft Visual Studio, NSLink installation provides a specific NSLink.xcconfig which may be used to substitute a different linker during the linking phase of XCode's build steps.

Let's start a new fresh XCode project. The project is a basic Command-line tool project.

test

You must first create a new Group element in your project by right-clicking on it. The following menu appears:

test

Select the New group button and name it (NSLink would be a wise choice).

test

Now right-click on your newly added Group and select New File... button:

test

Scroll all the way down to the Other category right-under the OS X family and select the following template:

test

You must give it a name (NSLinkOptions in the example) and you can also select targets from your project. For now, let us uncheck all targets:

test

Now we must create a configuration to overwrite the default linker. There are currently two important variables that are used by NSLink.xcconfig which are:

  • NSLINK_TARGET: The target architecture
  • NSLINK_FLAGS: Additionals flags which are passed to NSLink
Warning
These variables MUST BE SET before including NSLink.xcconfig!
test

You must now base all your configurations on the one you have previously added. To do so, you must click on your project name on the left-bar. Then, select your project in the middle panel. Make sure that Info tab is selected. You should now see the following screen:

test

As you can see, your configurations are set to No Configurations Set. You need to base your project on your newly added configuration file by selecting it from the following list:

test
Warning
Make sure to update the configuration of your project, NOT THE TARGETS.

Finally, your final Info tab should resemble the following two screens:

test
test

Now that everything has been updated, you must check that NSLink is used as the XCode's linker. You can now build your project. If the build is successfull, the logs may be viewed by selecting the following sub-panel:

test

Select the latest build and click on the right button of the Link phase. You should now see the NSLink's logo/header.

test