system/serenity
system/serenity
1
0
Fork 0
mirror of https://github.com/SerenityOS/serenity synced 2024-07-22 18:46:18 +00:00
Code Issues Actions 5 Packages Projects Releases Wiki Activity

Meta: Update CLion and WSL configuration documentations

Browse source 
This commit updates CLionConfiguration.md and NotesOnWSL.md so that
they comply with new build system. In addition to that, the WSL doc
is updated to include instructions to run qemu (and serenity) natively
on Windows, without needing an X-window server.
This commit is contained in:
Devashish 2020-05-17 19:26:46 +05:30 committed by Andreas Kling
parent 6060c7444b
commit e4f7080bbd
3 changed files with 199 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
Documentation/CLionConfiguration.md
View file

@ -1,8 +1,12 @@
## CLion Project Configuration
Configuring CLion for development requires a CMakeLists.txt file. The one provided in Meta/CLion packs the bare minimum configuration so that you can take advantage of code completion and basic error checking. This is not necessarily the best setup, there could be better ways to configure the IDE. Below instructions are intended for people not familiar with CMake, or who don't want to get bothered setting up the IDE first.
Configuring CLion for development requires a CMakeLists.txt file.
The one provided in Meta/CLion packs the bare minimum configuration required for code completion and basic error checking.
This is not necessarily the best setup, there could be better ways to configure the IDE.
Below instructions are intended for people not familiar with CMake, or who don't want to get bothered setting up the IDE first.
It's assumed that a directory named `serenity` contains all your source files. If you cloned the repository directly from GitHub, this is the directory that git creates to copy sources.
It's assumed that a directory named `serenity` contains all your source files.
If you cloned the repository directly from GitHub, this is the directory that git creates to copy sources.
- Create the project directory and cd to it: `mkdir serenity-project && cd serenity-project`
- Move `serenity` to the project directory: `mv <path/to/serenity> .`
@ -10,10 +14,42 @@ It's assumed that a directory named `serenity` contains all your source files. I
- Create new CMake project in IDE: `File->New CMake Project from Sources`
- In the file selection dialog, find and select `serenity-project`, then click OK.
The project will start loading. Building the index for the first time takes a while. Let it finish the first scan. Once it's done, you can start hacking :)
The project will start loading.
Building the index for the first time takes a while. Let it finish the first scan.
**Note:** Don't create a new git repo in `serenity-project`. The whole point of wrapping the sources to a new directory is to keep the project files created by CLion away from the main repository (the `.git` in `serenity`).
## Notes
**Note:** If you don't want the workspace to list files ending with certain extensions, go to `File->Settings->Editor->File Types` and add entries in the `Ignore files and folders` field.
**Note:** If you have created the project after building the toolchain, you may get errors on `make install` after moving `serenity` to the project directory.
If you move `serenity` out to its original location, the build will succeed again.
It is recommended that you create a script that merely moves `serenity` before attempting to rebuild and once the build finishes, moves `serenity` back to the project directory.
Also during the build, be careful not to switch to the IDE window.
Doing so will cause CLion to panic because the `serenity` directory has suddenly disappeared.
CLion will try to delete indexes and when the build finishes and `serenity` is moved back to the project directory, indexes will be built again. This is a waste of time.
In order to completely eliminate the rebuilding of indexes, you have to rebuild everything (toolchain included) from scratch while `serenity` resides in the project directory.
**Note:** If you have created the project after building serenity, you may get link errors on `makeall.sh` after moving `serenity` to the project directory. If you move `serenity` out to its original location, the build will succeed. It is recommended that you create a simple script that merely moves `serenity` before attempting to rebuild and once the build finishes, moves `serenity` back to the project directory. It's inconvenient, but kind of necessary.
**Note:** Don't create a new git repo in `serenity-project`.
The whole point of wrapping the sources to a new directory is to keep the project files away from the main git repository.
**Note:** If you don't want the workspace to list files ending with certain extensions, go to `File->Settings->Editor->File Types` and add entries to the `Ignore files and folders` field.
## Notes for WSL Users
It is possible to set the embedded terminal in CLion to the one that your WSL distribution provides.
This way you can build and run serenity without leaving the IDE.
Note that following will only help if you don't use an X-window server to access qemu.
It is possible to install qemu natively on Windows and allow WSL to use it instead of installing qemu first on (wsl) linux and then use X server to launch serenity inside of it.
Check the updated manual [here](https://github.com/SerenityOS/serenity/blob/master/Documentation/NotesOnWSL.md).
- Locate the terminal emulator for your linux distribution.
Open CMD with elevated privileges and cd to `C:/Program Files/WindowsApps/`.
The directory is usually hidden and requires additional privileges. You should be able to cd as administrator.
`dir` and look for your distribution in directory names. In case of Ubuntu, it starts with `CanonicalGroupLimited.Ubuntu20.04onWindows_2004.2020.424.0_x64`.
cd to it. The directory should contain the shell executable. In my case it's named `ubuntu2004.exe`.
Copy `absolute/path/to/ubuntu2004.exe`.
- Go to your IDE settings: `File->Settings->Tools->Terminal` and paste the path you just copied to `shell path`. Click OK.
- Close CLion and restart.
The default IDE terminal should now be changed to WSL, and now you can run `CLion/run.sh`.
You may also want to copy `serenity/Meta/CLion/run.sh` to your project directory and run it from there, so that you don't have to fight with git every time you modify the script.

35
Documentation/NotesOnWSL.md
View file

@ -1,21 +1,44 @@
## Notes on WSL
SerenityOS can also be built and run under WSL Version 2. WSL Version 1 is not supported since Version 1 does not support ext2, which is needed for the setup.
SerenityOS can also be built and run under WSL Version 2.
WSL Version 1 is not supported since Version 1 does not support ext2, which is needed for the setup.
WSL Version 2 is currently only available for Insider Builds of Windows which are more unstable and prone to crashes. Therefore, running SerenityOS on WSL Version 2 and running Insider Builds, in general, is not recommended on production systems.
WSL Version 2 is currently only available for Insider Builds of Windows which are more unstable and prone to crashes.
Therefore, running SerenityOS on WSL Version 2 and running Insider Builds, in general, is not recommended on production systems.
Nevertheless, here is a guide on how to [get an Insider Build](https://insider.windows.com/en-us/how-to-pc/) and how to [get WSL2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install). Once installed, you will need to make sure the distribution you want to use (and the new default) is using Version 2:
Nevertheless, here is a guide on how to [get an Insider Build](https://insider.windows.com/en-us/how-to-pc/) and how to [get WSL2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-install).
Once installed, you will need to make sure the distribution you want to use (and the new default) is using Version 2:
- `wsl -l -v` will list distros and versions,<br/>
- `wsl --set-version <distro> <version` is used to convert a distro to another version, and<br/>
- `wsl --set-version <distro> <version>` is used to convert a distro to another version, and<br/>
- `wsl --set-default-version 2` will set the default version for all new distros (if desired.)<br/>
The installation then proceeds as usual.
WSL2 does not natively support graphical applications. This means that to actually **./run** SerenityOS, you need an X Server for windows. [Vcxsrv](https://sourceforge.net/projects/vcxsrv/) is a good option. When you start up Vcxsrv, make sure to set the Display number to 0, and to Disable access control. Before actually doing **./run**, you need to set the DISPLAY environmental variable as such:
WSL2 does not natively support graphical applications.
You can either install qemu natively on windows and allow WSL to talk to it, or you can install an X Server for windows.
### Setting up an X server with WSL:
- Install [Vcxsrv](https://sourceforge.net/projects/vcxsrv/) on Windows.
- When you start up Vcxsrv, make sure to set the Display number to 0, and to Disable access control.
- Before actually doing **make run**, you need to set the DISPLAY environmental variable as such:
```bash
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
```
This is due to a bug in WSL2. For more information, microsoft/WSL#4106.
- Connect to the window server from WSL.
Now you can finally, **./run**.
Now you can finally, **make run**.
### Using native Qemu install with WSL:
- Grab latest qemu from [here](https://www.qemu.org/download/#windows) and install for windows.
- Locate the executable `qemu-system-i386.exe` in WSL.
In a 64-bit machine, it's located at `/mnt/c/Program Files/qemu/qemu-system-i386.exe`.
- Edit `serenity/Meta/CLion/run.sh`. Set **SERENITY_QEMU_BIN** to point to the windows installation of `qemu-system-i386.exe`.
Also verify that the value of **SERENITY_BUILD** is valid.
In a 64-bit machine, if qemu was installed in the default location you shouldn't need to alter anything.
- Execute `serenity/Meta/CLion/run.sh`.

128
Meta/CLion/run.sh Normal file
View file

@ -0,0 +1,128 @@
#!/bin/sh
# shellcheck disable=SC2086 # FIXME: fix these globing warnings
set -e
#SERENITY_PACKET_LOGGING_ARG="-object filter-dump,id=hue,netdev=breh,file=e1000.pcap"
[ -e /dev/kvm ] && [ -r /dev/kvm ] && [ -w /dev/kvm ] && SERENITY_KVM_ARG="-enable-kvm"
[ -z "$SERENITY_BOCHS_BIN" ] && SERENITY_BOCHS_BIN="bochs"
# set this to point to qemu installation on windows
[ -z "$SERENITY_QEMU_BIN" ] && SERENITY_QEMU_BIN="/mnt/c/Program Files/qemu/qemu-system-i386.exe"
[ -z "$SERENITY_KERNEL_CMDLINE" ] && SERENITY_KERNEL_CMDLINE="hello"
[ -z "$SERENITY_RAM_SIZE" ] && SERENITY_RAM_SIZE=256M
[ -z "$SERENITY_COMMON_QEMU_ARGS" ] && SERENITY_COMMON_QEMU_ARGS="
$SERENITY_EXTRA_QEMU_ARGS
-s -m $SERENITY_RAM_SIZE
-cpu max
-d cpu_reset,guest_errors
-smp 2
-device VGA,vgamem_mb=64
-hda _disk_image
-device ich9-ahci
-debugcon stdio
-soundhw pcspk
-soundhw sb16
"
[ -z "$SERENITY_COMMON_QEMU_Q35_ARGS" ] && SERENITY_COMMON_QEMU_Q35_ARGS="
$SERENITY_EXTRA_QEMU_ARGS
-s -m $SERENITY_RAM_SIZE
-cpu max
-machine q35
-d cpu_reset,guest_errors
-smp 2
-device VGA,vgamem_mb=64
-device piix3-ide
-drive file=_disk_image,id=disk,if=none
-device ide-hd,bus=ide.6,drive=disk,unit=0
-debugcon stdio
-soundhw pcspk
-soundhw sb16
"
# set this to the Build directory in serenity
SERENITY_BUILD="/mnt/c/Users/Ragnarok/serenity-project/serenity/Build"
cd "$SERENITY_BUILD" || exit
make install
make image
export SDL_VIDEO_X11_DGAMOUSE=0
if [ "$1" = "b" ]; then
# ./run b: bochs
$SERENITY_BOCHS_BIN -q -f .bochsrc
elif [ "$1" = "qn" ]; then
# ./run qn: qemu without network
"$SERENITY_QEMU_BIN" \
$SERENITY_COMMON_QEMU_ARGS \
-device e1000 \
-kernel Kernel/Kernel \
-append "${SERENITY_KERNEL_CMDLINE}"
elif [ "$1" = "qtap" ]; then
# ./run qtap: qemu with tap
sudo "$SERENITY_QEMU_BIN" \
$SERENITY_COMMON_QEMU_ARGS \
$SERENITY_KVM_ARG \
$SERENITY_PACKET_LOGGING_ARG \
-netdev tap,ifname=tap0,id=br0 \
-device e1000,netdev=br0 \
-kernel Kernel/Kernel \
-append "${SERENITY_KERNEL_CMDLINE}"
elif [ "$1" = "qgrub" ]; then
# ./run qgrub: qemu with grub
"$SERENITY_QEMU_BIN" \
$SERENITY_COMMON_QEMU_ARGS \
$SERENITY_KVM_ARG \
$SERENITY_PACKET_LOGGING_ARG \
-netdev user,id=breh,hostfwd=tcp:127.0.0.1:8888-10.0.2.15:8888,hostfwd=tcp:127.0.0.1:8823-10.0.2.15:23 \
-device e1000,netdev=breh
elif [ "$1" = "q35_cmd" ]; then
SERENITY_KERNEL_CMDLINE=""
# FIXME: Someone who knows sh syntax better, please help:
for _ in $(seq 2 $#); do
shift
SERENITY_KERNEL_CMDLINE="$SERENITY_KERNEL_CMDLINE $1"
done
echo "Starting SerenityOS, Commandline: ${SERENITY_KERNEL_CMDLINE}"
# ./run: qemu with SerenityOS with custom commandline
"$SERENITY_QEMU_BIN" \
$SERENITY_COMMON_QEMU_Q35_ARGS \
$SERENITY_KVM_ARG \
-netdev user,id=breh,hostfwd=tcp:127.0.0.1:8888-10.0.2.15:8888,hostfwd=tcp:127.0.0.1:8823-10.0.2.15:23 \
-device e1000,netdev=breh \
-kernel Kernel/Kernel \
-append "${SERENITY_KERNEL_CMDLINE}"
elif [ "$1" = "qcmd" ]; then
SERENITY_KERNEL_CMDLINE=""
# FIXME: Someone who knows sh syntax better, please help:
for _ in $(seq 2 $#); do
shift
SERENITY_KERNEL_CMDLINE="$SERENITY_KERNEL_CMDLINE $1"
done
echo "Starting SerenityOS, Commandline: ${SERENITY_KERNEL_CMDLINE}"
# ./run: qemu with SerenityOS with custom commandline
"$SERENITY_QEMU_BIN" \
$SERENITY_COMMON_QEMU_ARGS \
$SERENITY_KVM_ARG \
-netdev user,id=breh,hostfwd=tcp:127.0.0.1:8888-10.0.2.15:8888,hostfwd=tcp:127.0.0.1:8823-10.0.2.15:23 \
-device e1000,netdev=breh \
-kernel Kernel/Kernel \
-append "${SERENITY_KERNEL_CMDLINE}"
else
# ./run: qemu with user networking
"$SERENITY_QEMU_BIN" \
$SERENITY_COMMON_QEMU_ARGS \
$SERENITY_KVM_ARG \
$SERENITY_PACKET_LOGGING_ARG \
-netdev user,id=breh,hostfwd=tcp:127.0.0.1:8888-10.0.2.15:8888,hostfwd=tcp:127.0.0.1:8823-10.0.2.15:23,hostfwd=tcp:127.0.0.1:8000-10.0.2.15:8000,hostfwd=tcp:127.0.0.1:2222-10.0.2.15:22 \
-device e1000,netdev=breh \
-kernel Kernel/Kernel \
-append "${SERENITY_KERNEL_CMDLINE}"
fi