aboutsummaryrefslogtreecommitdiffstats
path: root/docs/part-2/3_xds-cli.md
blob: a5610c1e18cc10cdc18884b3ebe0c0926faec5b6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
# xds-cli: command-line tool for XDS

`xds-cli` is a command-line tool for X(cross) Development System.

## Configuration

`xds-cli` configuration is defined either by environment variables or by
setting command line options.
Configuration through environment variables may also be defined in a file that
will be sourced by `xds-cli` on start-up. Use `--config|-c` option or set
`XDS_CONFIG` environment variable to specify the config file to use.

So configuration is driven either by environment variables or by command line
options or using a config file knowing that the following priority order is used:

1. use option value (for example use project ID set by `--id` option),
1. else use variable `XDS_xxx` (for example `XDS_PROJECT_ID` variable) when a
   config file is specified with `--config|-c` option,
1. else use `XDS_xxx` (for example `XDS_PROJECT_ID`) environment variable

<!-- note -->
**Note:** all parameters after a double dash (--) are considered as the command
to execute on xds-server.
<!-- endnote -->

### Global Options / Configuration variables

Following is the list of global options across all sub-commands.

__`--config|-c` option or `XDS_CONFIG` env variable__

Env config file to source on startup

__`--log|-l` option or `XDS_LOGLEVEL` env variable__

Logging level, supported levels are:

- panic,
- fatal,
- error,
- warn,
- info,
- debug

Default level is "error".

__`--rpath` option or `XDS_PATH` env variable__

Relative path into project

__`timestamp|-ts` option or `XDS_TIMESTAMP` env variable__

Prefix output with timestamp

__`url` option or `XDS_AGENT_URL` env variable__

Local XDS agent url (default: "localhost:8800")

## Commands

### projects

`projects` (short `prj`) command should be used to managed XDS projects.
This command supports following sub-commands:

```bash
add, a      Add a new project
get         Get a property of a project
list, ls    List existing projects
remove, rm  Remove an existing project
sync        Force synchronization of project sources
```

Here are some usage examples:

```bash
# Create/declare a new project
xds-cli prj add --label "ABeautifulName" --type pm -p /home/seb/xds-workspace/myProject -sp /home/devel/xds-workspace/myProject

# List projects
xds-cli prj ls

# Delete an existing project
xds-cli prj rm 8e49
```

### sdks

`sdks` (alias `sdk`) command should be used to managed cross SDKs.
This command supports following sub-commands:

```bash
add, a      Add a new SDK
get         Get a property of a SDK
list, ls    List installed SDKs
remove, rm  Remove an existing SDK
```

Here are some usage examples:

```bash
# List existing SDKs
xds-cli sdks ls

# Get SDK info
xds-cli sdks get c64d
```

### exec

`exec` command should be used to exec command through XDS system. For example
you can use this command to build your project in XDS system.
This command supports following sub-commands:

`exec` command options are:

__`--id` option or `XDS_PROJECT_ID` env variable (**mandatory option**)__

project ID you want to build

__`--rpath` (short `-p`) or `XDS_RPATH` env variable__

relative path into project

__`--sdkid` (alias `--sdk`) or `XDS_SDK_ID` env variable (**mandatory option**)__

Cross Sdk ID to use to build project

Here are some usage examples:

```bash
cd $MY_PROJECT_DIR
mkdir build

# Generate build system using cmake
xds-cli exec --id=4021 --sdkid=c226 -- "cd build && cmake .."

# Build the project
xds-cli exec --id=4021 --sdkid=c226 -- "cd build && make all"
```

In case of `xds-agent` is not running on default url:port (that is `localhost:8800`)
you can specify the url using `--url` option :

```bash
xds-cli --url=http://localhost:8800 exec --id=4021 --sdkid=c226 -- "cd build && make all"
```

### misc

`misc` command allows to execute miscellaneous sub-commands such as:

```bash
version, v   Get version of XDS agent and XDS server
status, sts  Get XDS configuration status (including XDS server connection)
```

Here are some usage examples:

```bash
xds-cli misc version --verbose

xds-cli misc sts
```

## How to build

### Prerequisites

 You must install and setup [Go](https://golang.org/doc/install) version 1.8.1 or
 higher to compile this tool.

### Building

Clone this repo into your `$GOPATH/src/github.com/iotbzh` and use delivered Makefile:

```bash
 export GOPATH=$(realpath ~/workspace_go)
 mkdir -p $GOPATH/src/github.com/iotbzh
 cd $GOPATH/src/github.com/iotbzh
 git clone https://github.com/iotbzh/xds-cli.git
 cd xds-cli
 make
```

## Debug

Visual Studio Code launcher settings can be found into `.vscode/launch.json`.

>**Tricks:** To debug both `xds-cli` and `xds-agent` (REST API part) or common
code `xds-common`, it may be useful use the same local sources.
So you should replace `xds-agent` + `xds-common` in `vendor` directory by a symlink.
So clone first `xds-agent` + `xds-common` sources next to `xds-cli` directory.
You should have the following tree:

```bash
> tree -L 3 src
src
|-- github.com
    |-- iotbzh
       |-- xds-agent
       |-- xds-cli
       |-- xds-common
```

Then invoke `vendor/debug` Makefile rule to create a symlink inside vendor
directory :

```bash
cd src/github.com/iotbzh/xds-cli
make vendor/debug
```