Thursday, July 4, 2024

GitLab Cheat Sheet

In 2016, we checked out GitHub Cheat Sheet: a distributed version control system for Open Source projects. Now we will explore differences in GitLab to streamline collaborative workflow and leverage CI/CD pipelines.

Let's check it out!

As per previous post assumes an account setup on Create an account on if you have not already done so. As GitLab also uses underlying git we setup the following on localhost for development:

SSH Keys
An SSH key is an access credential for the SSH network protocol. Git supports both RSA and ED25519 keys. Launch Terminal. Issue the following commands to generate new SSH key and adding SSH key to ssh-agent:

 RSA  ED25519
 cd ~/.ssh  cd ~/.ssh
 ssh-keygen -t rsa -b 4096 -C ""  ssh-keygen -t ed25519 -C <email>
 Passphrase <redacted>  Passphrase <redacted>
 eval "$(ssh-agent -s)"  eval "$(ssh-agent -s)"
 ssh-add ~/.ssh/id_rsa  ssh-add ~/.ssh/id_ed25519
 xclip -selection clipboard < ~/.ssh/  xclip -selection clipboard < <key>

If xclip is not installed then issue 2x commands: sudo apt-get update and sudo apt-get install xclip. Finally, navigate to Settings | SSH and GPG keys | New SSH key | Paste contents from here.

Personal Access Token
If you favor HTTPS then Personal Access Tokens offer security benefits over password-based authentication. Launch Navigate to Edit Profile | Access Tokens | Add new token. Create personal access token.

After new Personal Access Token is created upload into source control software for example Source Tree on Windows and Mac OS/X and JetBrains products on Linux that integrate Git like PyCharm for Python etc etc.

Source Tree
Launch Source Tree | Settings | Accounts Add... | Enter the following details | Paste personal access token:

JetBrains IDE
Launch PyCharm | File | Settings... | Version Control | GitLab. Click "+" button | Enter GitLab token | Log In:

In 2021, we coded an example from scratch as full end-to-end Web API demo on local host, in Docker and Kubernetes. Let's replicate with Python Flask API but this time include Gitlab CI/CD deployment pipelines.

Navigate to Create blank project. Launch PyCharm. Create the new project gitlabcheatsheet.

Enter code. Install packages. Press F5 to debug. Launch Terminal | curl http://localhost:8080  Dockerfile
 from flask import Flask
 app = Flask(__name__)
 def root():
     return "Hello World (Python)!\n"
 if __name__ == "__main__":"", port=8080)
 FROM python:3-alpine
 WORKDIR /service
 COPY requirements.txt .
 RUN pip install -r requirements.txt
 COPY . ./
 EXPOSE 8080
 ENTRYPOINT ["python3", ""]

Code Dockefile. Launch Terminal | Enter the following Docker commands | curl http://localhost:8080
 docker build --pull --rm -f "Dockerfile" -t flask-api:latest "."
 docker run --rm -d -p 8080:8080/tcp flask-api:latest --name "flask-api"

Create local KinD cluster. Enter all the following Kubernetes Deployment and Service YAML configuration:
 --- Deployment
 apiVersion: apps/v1
 kind: Deployment
   name: flask-api-deployment
   namespace: test-ns
   replicas: 1
       app: flask-api
         app: flask-api
         - name: flask-api
           image: flask-api:latest
           imagePullPolicy: Never
             - containerPort: 8080
 --- Service
 apiVersion: v1
 kind: Service
   name: flask-api-service
   namespace: test-ns
     app: flask-api
   type: NodePort
     - protocol: TCP
       port: 80
       targetPort: 8080

Finally test: Launch Terminal | Enter the following Kubernetes commands | curl http://localhost:8080
 kubectl config set-context --current --namespace=test-ns
 kind load docker-image flask-api:latest --name flask-cluster
 kubectl apply -f Kubernetes.yaml
 kubectl port-forward service/flask-api-service 8080:80
 curl http://localhost:8080

Extend example but this time include Gitlab CI/CD deployment pipelines. Ensure you have all Pre-Requisites:
 Python 3.8
 GitLab account [CI/CD]
 Microsoft Azure subscription [AZ CLI]
 VS Code Docker + Kubernetes
 Docker Hub account
 Kubernetes in Docker [KinD]
 docker [CLI]
 kubectl [CLI]

Azure AKS
Launch Terminal | Login to Azure portal. Enter commands to extract Service Principal and generate SSH key:
 az login
 az ad sp create-for-rbac --name ${USER}-bz-sp
 cd ~/.ssh
 ssh-keygen -t rsa -b 4096 -N '' -f master_ssh_key
 eval $(ssh-agent -s)
 ssh-add master_ssh_key

Export the following environment variables. Note: use the Service Principal information for first 3x ENV VARs
 export AZ_SP_ID=<value_from_appId>
 export AZ_SP_PASSWORD=<value_from_password>
 export AZ_TENANT_ID=<value_from_tenant
 export CLUSTER_NAME=stevepro-dev-cluster
 export MASTER_SSH_KEY=~/.ssh/
 export AZ_NETWORK_MODE=transparent
 export AZ_LB_SKU=standard
 export AZ_VM_SIZE=Standard_D2s_v3
 export AZ_LOCATION=northeurope

Create the Azure resource group then finally create the AKS cluster. Note: this process can take few minutes
 az group create --name ${CLUSTER_NAME} --location ${AZ_LOCATION} --debug
 az aks create --name ${CLUSTER_NAME} --resource-group ${CLUSTER_NAME} \
  --dns-name-prefix ${CLUSTER_NAME} --node-count ${CLUSTER_NODES} \
  --node-vm-size ${AZ_VM_SIZE} --kubernetes-version ${KUBERNETES_VERSION} \
  --ssh-key-value ${MASTER_SSH_KEY} --service-principal ${AZ_SP_ID} \
  --client-secret ${AZ_SP_PASSWORD} --load-balancer-sku ${AZ_LB_SKU} \
  --network-plugin azure --debug

Finally, execute following commands to download + export KUBECONFIG file on localhost and setup context
 export KUBECONFIG=~/.kube/config
 az aks get-credentials --name ${CLUSTER_NAME} \
  --resource-group ${CLUSTER_NAME} --file ${KUBECONFIG}
 kubectl create ns test-ns
 kubectl config set-context --current --namespace=test-ns

Follow this tutorial to create and run your first GitLab CI/CD pipeline. Create .gitlab-ci.yml file at root the of the project directory. Refactor all YAML configuration in files beneath the cicd directory. Automate CI/CD to the Kubernetes cluster using helm charts. This way, multiple environments can be targeted and customized.

Navigate to | Settings | CI/CD | Variables. Enter all GitLab Variables here e.g. Docker registry host and username. Secure sensitive information like Docker password using Base64. Add KUBECONFIG:

Trigger CI/CD pipeline. Launch Terminal | Repeat kubectl port-forward. Test: curl http://localhost:8080

 kubectl port-forward service/flask-api-service 8080:80
 curl http://localhost:8080

Gitflow is an alternative Git branching model that involves the use of feature branches and multiple primary branches. Here is practical guide to implement GitFlow using GitLab with the corresponding git commands.

Launch Create new project. Default branch will be main. Git clone repository to localhost. For completeness cut initial Tag 0.1. In SourceTree setup GitFlow: Repository | Git-flow | Initialize Repository:

In set develop as default branch: GitLab | Setttings | Repository | Branch defaults | develop.
 FEATURE [start]
 git checkout -b feature/my-feature develop # cut feature branch
 git push --set-upstream origin feature/my-feature # push feature to remote
 git checkout develop 
 git merge --no-ff feature/my-feature # merge feature to develop
 git push # push develop to remote
 FEATURE [end]
 git branch -d feature/my-feature # delete local branch
 git push origin -d feature/my-feature # delete remote branch
 RELEASE [start]
 git checkout -b release/1.0 develop # cut release branch
 git push --set-upstream origin release/1.0 # push release to remote
 BUGFIX [start]
 git checkout -b bugfix/1.0 release/1.0 # cut bugfix branch
 git push --set-upstream origin bugfix/1.0 # push bugfix to remote
 git checkout release/1.0 
 git merge --no-ff bugfix/1.0 # merge bugfix to release
 git push # push release to remote
 BUGFIX [end]
 git branch -d bugfix/1.0 # delete local branch
 git push origin -d bugfix/1.0 # delete remote branch
 RELEASE [end]
 git checkout main 
 git merge --no-ff release/1.0 # merge release to main
 git push # sync release with main
 git tag -a 1.0 -m "Tag 1.0" # cut tag 1.0 off main
 git push origin tag 1.0 # push tag 1.0 to remote
 git checkout develop 
 git merge --no-ff release/1.0 # merge release to develop
 git push # sync release with develop
 git branch -d release/1.0 # delete local branch
 git push origin -d release/1.0 # delete remote branch
 HOTFIX [start]
 git checkout main 
 git checkout -b hotfix/1.1 main # cut hotfix branch
 git push --set-upstream origin hotfix/1.1 # push hotfix to remote
 HOTFIX [end]
 git checkout main 
 git merge --no-ff hotfix/1.1 # merge hotfix to main
 git push # sync hotfix with main
 git tag -a 1.1 -m "Tag 1.1" # cut Tag 1.1 off main
 git push origin tag 1.1 # push Tag 1.1 to remote
 git checkout develop 
 git merge --no-ff hotfix/1.1 # merge hotfix to develop
 git push # sync hotfix with develop
 git branch -d hotfix/1.1 # delete local branch
 git push origin -d hotfix/1.1 # delete remote branch

IMPORTANT - you can compare two branches [source vs. target] anytime issuing the following commands:
 git checkout develop # source branch
 git diff --name-only main # target branch
 OR # target branch
 git diff-tree --no-commit-id --name-only -r main..develop # source vs. target branch

To summarize, now that we have discussed the differences between GitHub and GitLab, we have extended our previous end-to-end Web API demo on local host, in Docker and Kubernetes but now leveraged GitLab CI/CD pipelines to automate deployments to the cloud. Our next steps would be more GitFlow integration: Replicate deployments across multiple environments and complete the full Software Development LifeCyle!

Saturday, June 1, 2024

MacOS Setup Cheat Sheet II

In the previous post we checked out MacOS Setup Cheat Sheet to seamlessly transfer all keyboard shortcuts from Windows to Mac. Now we would like to transfer all Application navigation as M1 powered MacBooks are more appealing for companies than ever. Especially with the rise of A.I. requirements for faster data access.

Let's check it out!

In the previous post, we began looking at using keyboard shortcuts on Mac. Now we would like to compare document shortcuts that we are used to for navigation on Windows however now using Ctrl instead of Cmd:
 Home  Move to beg of line  Ctrl + Home  Move to beg of file
 End  Move to end of line  Ctrl + End  Move to end of file
 Ctrl + Left  Move to prev word  Ctrl + Shift + Left  Select the prev word
 Ctrl + Right  Move to next word  Ctrl + Shift + Right  Select the next word
 Shift + Home  Select to beg of line  Ctrl + Shift + Home  Select to beg of file
 Shift + End  Select to end of line  Ctrl + Shift + End  Select to end of file
The main issue is there doesn't seem to be generic shortcut mapping; navigation seems application specific!

The Mac text system uses generalized key bindings mechanism that is completely re-mappable by all users. The standard bindings include all system defaults but you can override bindings in your own custom dict file:
 SYSTEM /System/Library/Frameworks/AppKit.framework/Resources/StandardKeyBinding.dict
 CUSTOM ~/Library/KeyBindings/DefaultKeyBinding.dict

Here is how to override MacOS key bindings: Launch Terminal and create new a DefaultKeyBinding.dict file:
 sudo bash
 mkdir -p ~/Library/KeyBindings
 touch ~/Library/KeyBindings/DefaultKeyBinding.dict
 open -e ~/Library/KeyBindings/DefaultKeyBinding.dict

Typically, the default key bindings for the Home and End keys in MacOS are different to any other operating system. Thus you may like to fix the Home and End buttons first and in combination with Shift and Ctrl keys.

Next key bindings that may not be working is to move cursor from word to word. Integrate Keycode Modifier learnt from the previous post to complete custom dict file to change all MasOS key bindings. Here is my file:
  "\UF729" =  "moveToBeginningOfLine:" /* Home Button*/
  "\UF72B" =  "moveToEndOfLine:" /* End Button */
  "$\UF729" =  "moveToBeginningOfLineAndModifySelection:" /* Shift+ Home Button */
  "$\UF72B" =  "moveToEndOfLineAndModifySelection:" /* Shift+ End Button */
  "@\UF729" =  "moveToBeginningOfDocument:" /* Ctrl + Home Button */
  "^\UF729" =  "moveToBeginningOfDocument:" /* Alt + Home Button */
  "~\UF729" =  "moveToBeginningOfDocument:" /* Win + Home Button */
  "@\UF72B" =  "moveToEndOfDocument:" /* Ctrl + End Button */
  "^\UF72B" =  "moveToEndOfDocument:" /* Alt + End Button */
  "~\UF72B" =  "moveToEndOfDocument:" /* Win + End Button */
  "@$\UF729" =  "moveToBeginningOfDocumentAndModifySelection:" /* Ctrl + Shift + Home Button */
  "^$\UF729" =  "moveToBeginningOfDocumentAndModifySelection:" /* Alt + Shift + Home Button */
  "~$\UF729" =  "moveToBeginningOfDocumentAndModifySelection:" /* Win + Shift + Home Button */
  "@$\UF72B" =  "moveToEndOfDocumentAndModifySelection:" /* Ctrl + Shift + End Button */
  "^$\UF72B" =  "moveToEndOfDocumentAndModifySelection:" /* Alt + Shift + End Button */
  "~$\UF72B" =  "moveToEndOfDocumentAndModifySelection:" /* Win + Shift + End Button */
  "@\UF702" =  "moveWordLeft:" /* Ctrl + Left */
  "^\UF702" =  "moveWordLeft:" /* Alt + Left */
  "~\UF702" =  "moveWordLeft:" /* Win + Left */
  "@\UF703" =  "moveWordRight:" /* Ctrl + Right */
  "^\UF703" =  "moveWordRight:" /* Alt + Right */
  "~\UF703" =  "moveWordRight:" /* Win + Right */
  "@$\UF702" =  "moveWordLeftAndModifySelection:" /* Ctrl + Shift + Left */
  "^$\UF702" =  "moveWordLeftAndModifySelection:" /* Alt + Shift + Left */
  "~$\UF702" =  "moveWordLeftAndModifySelection:" /* Win + Shift + Left */
  "@$\UF703" =  "moveWordRightAndModifySelection:" /* Ctrl + Shift + Right */
  "^$\UF703" =  "moveWordRightAndModifySelection:" /* Alt + Shift + Right */
  "~$\UF703" =  "moveWordRightAndModifySelection:" /* Win + Shift + Right */
For completeness, here is a thorough KeyBindings tutorial explaining MacOS Keybinding Key Syntax and the Action Code. Detailed DefaultKeyBinding.dict examples shared online by users Belphemu, trusktr and zsimic.

Finally, in researching Default Key Bindings many posts promote Karabiner-Elements as a powerful keyboard customizer for macOS. However, it has been recommended not to use on M1 hardware due to kernel panics.

Ideally we would like to update navigation on Terminal due to frequent use: Terminal | Settings... | Profiles. Keyboard tab customize Key and Action settings. Check Use Option as Meta Key to "backward delete word". Unfortunately, Terminal navigation not aligned therefore will prefer IDEs like VS Code or PyCharm terminals.

VS Code
Visual Studio Code is a cross-platform code editor available on Windows, Linux and Mac. However, unlike the TextEdit, VS Code does not respect DefaultKeyBinding.dict on MacOS. Therefore, change keyboard shorcuts!

Customize VS Code keybindings to align navigation: Launch VS Code | Settings | Keyboard Shortcuts | Add:
 Command Keybinding Description
 cursorTop Ctrl + Home Move to beg of file
 cursorBottom Ctrl + End Move to end of file
 cursorWordLeft Ctrl + Left Move to prev word
 cursorWordRight Ctrl + Right Move to next word
 cursorTopSelect Ctrl + Shift + Home Select to beg of file
 cursorBottomSelect Ctrl + Shift + End Select to end of file
 cursorWordLeftSelect Ctrl + Shift + Left Select the prev word
 cursorWordRightSelect Ctrl + Shift + Right Select the next word
 deleteWordLeft Alt + Backspace Delete the prev word

Continue to customize Menu keyboard shortcuts that one is accustomed to aligning VS Code navigation e.g.:
 Command Keybinding Description
 File: Open Folder... Ctrl + K Ctrl + O workbench.action.files.openFolderViaWorkspace
 Terminal: Clear Ctrl + L workbench.action.terminal.clear
 Terminal: Create New Terminal Ctrl + Shift + T

The keybindings for VS Code are updated in ~/Library/Application\ Support/Code/User/keybindings.json file. Update keybindings.json directly for Terminal keyboard shortcuts like delete word prior + cursor movement:
  "key": "alt+backspace",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b\u007f" },
  "when": "terminalFocus"
  "key": "cmd+backspace",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001b\u007f" },
  "when": "terminalFocus"
  "key": "cmd+left",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001bb" },
  "when": "terminalFocus"
  "key": "cmd+right",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u001bf" },
  "when": "terminalFocus"
  "key": "cmd+z",
  "command": "workbench.action.terminal.sendSequence",
  "args": { "text": "\u0003" },
  "when": "terminalFocus"

PyCharm Community
Align PyCharm Keymap to VS Code Keymap for consistent keyboard shortcuts and developer IDE experience. In the "Welcome to PyCharm" popup choose Plugins | VSCode Keymap | Install. Navigate back to Customize. Under Keymap change default value VSCode (macOS). Now most VS Code shortcuts will work like Windows.

However, in order to better align full navigation, update the following from PyCharm | Settings... | Keymap:
 Editor Actions Move Caret to Text Start Ctrl + Home
 Editor Actions Move Caret to Text End Ctrl + End
 Editor Actions Move Caret to Text Start with Selection Ctrl + Shift + Home
 Editor Actions Move Caret to Text End with Selection Ctrl + Shift + End
 Editor Actions Move Caret to Previous Word Ctrl + Left
 Editor Actions Move Caret to Next Word Ctrl + Right
 Editor Actions Move Caret to Previous Word with Selection Ctrl + Shift + Left
 Editor Actions Move Caret to Next Word with Selection Ctrl + Shift + Right
 Editor Actions Move Up and Scroll with Selection Ctrl + Shift + Up
 Editor Actions Move Down and Scroll with Selection Ctrl + Shift + Down
 Editor Actions Delete to Word Start Alt + Backspace
 Main Menu Navigate Back Alt + Up
 Main Menu Navigate Forward Alt + Down
IMPORTANT: typically use Alt + Left to Navigate Back but this is now doubled to Move Word left as priority!

If Ctrl + Shift + O launches Symbols then remove duplicate: Choose Settings | Keymap | filter as "symbol". Double click Navigate | Go to Symbol | Edit | Remove Ctrl+Shift+O | Apply | OK. Repeat this as necessary.

Keyboard shortcuts in Excel like Ctrl+Home and Ctrl+End won't work so prefer to use arrow keys to navigate
 Ctrl + Left Move to first cell of selected row
 Ctrl + Right Move to last cell of selected row
 Ctrl + Up Move to first cell of selected column
 Ctrl + Down Move to last cell of selected column

PostgreSQL is preferred by companies because it offers data types not found in MySQL. Plus MySQL can be used for web-based/online or mapping functions, whereas PostgreSQL is recommended for large analytical processes.

Setup a local PostgreSQL database server on Mac OS/X. Download PostgreSQL 16 (Universal).

Download and install local pgAdmin database client on Mac OS/X to administer and PostgreSQL instances.

PyCharm Professional
After installing Postgres server one can use pgAdmin client for data access. However, it seems challenging to customize navigation here. An excellent alternative is Database Tools + SQL plugin available from PyCharm.

This plugin is available only in PyCharm Professional but may prove to be a valuable investment longterm J
 PyCharm Community  PyCharm Professional

Download and install PyCharm Professional for macOS. Launch PyCharm Professional. Import Settings from PyCharm Community Edition. Thus you should have all navigation aligned! Note the Database Tools + SQL plugin will be enabled by default. Interesting plugins PostgreSQL Debugger and SQL Optimizer + Indexing.

Connect to database: View menu | Database | Click "+" | Data Source | PostgreSQL. Enter credentials | OK.

Checkout the PyCharm documentation to Run queries. Align F5 to Execute queries similar to SQL Server Mgt Studio: Settings | Keymap | Database | Console Toolbar | Execute. Right click | Add keyboard shortcut | F5.

Checkout the PyCharm documentation to update Word Case as per SQL convention: Settings | Editor | Code Style | SQL | PostgreSQL. Inherit general SQL style DISABLE | Word Case | Keywords To upper. Also update Code Completion as Ctrl + Space: Settings | Keymap | Main Menu | Code | Code Completion | Ctrl + Space.

Finally in Settings | Editor | General | Code Completion enable the following options: Automatically insert single suggestions, Sort suggestions alphabetically, Show suggestions as you type, Match case: First letter.

To summarize, armed with this knowledge we have setup the MacOS to better align keyboard shortcuts and application navigation techniques accumulated from years of Windows development experience. From here, we are in now an excellent position to leverage the M1 chip for faster data access as per A.I. requirements!

Wednesday, May 1, 2024

MacOS Setup Cheat Sheet

In late 2020, Apple unleashed its industry-leading performant M1 chip designed specifically for the Mac. As a result, M1 powered MacBooks have provened to be much faster than Windows thus making Apple computers more appealing for companies than ever. Especially with the rise of A.I. requirements for faster data access.

The issue now for Windows users is to seamlessly transfer all keyboard shortcuts + muscle memory to Mac!

Let's check it out!

If you are new to the Mac then the first thing to do is acquaint yourself with keyboard shortcuts as outlined in various online documentation pages and especially with what are those symbols shown in menus on Mac:

The major differences between Windows and Mac keyboards are the special keys found on either side of the spacebar known as modifier keys and are typically used for System Keybindings. Here is quick comparison:
 Location Windows Mac OS Keycode Modifier Menu Symbol
 Left Ctrl Ctrl @ ⌃
 Middle WinKey Option ~ ⌥
 Right Alt Command ^ ⌘
 Left Shift Shift $ ⇧

Out-of-the-box, there are some common keyboard shortcuts shared across Windows and Mac, for example:
 Alt + Tab Toggle between all open applications
 Ctrl + Tab Toggle between all open tabs within an application

However, for all common Ctrl + type Windows keyboard shortcuts the Mac prefers to use the Command key:
 Ctrl + A Select all  Ctrl + Q Quit application
 Ctrl + C Copy item  Ctrl + S Save item
 Ctrl + F Find item  Ctrl + V Paste item
 Ctrl + N New item  Ctrl + W Close window
 Ctrl + O Open item  Ctrl + X Cut item
 Ctrl + P Print item  Ctrl + Z Undo action

Therefore, remap the modifier keys in System Settings | Keyboard | Keyboard Shortcuts... | Modifier Keys:

IMPORTANT: in order to retain Alt + Tab functionality we have now had to re-map Option to Command also! There is an AltTab utility but companies may disallow the installation of third party software, unfortunately.

System Settings
Customize your Mac with System Settings. Launch System Settings from Dock and make following changes:
 General Language & Region Region = New Zealand
 Appearance Show scroll bars Automatically based on mouse or trackpad
 Accessibility Pointer Control | Trackpad Options Use trackpad for scrolling = DISABLED
 Desktop & Dock Dock Size = Small
 Desktop & Dock Dock  Position on screen = Left
 Desktop & Dock Desktop & Stage Manager Click wallpaper to reveal desktop =
 Only in Stage Manager
 Desktop & Dock Group windows by application DISABLED
 Desktop & Dock Displays have separate Spaces DISABLED
 Displays Dual Monitors 1920 x 1080 (Default)
 Users & Groups Administrator Update login photo
 Keyboard Key repoeat rate Fast
 Keyboard Delay until repeat Short
 Keyboard Turn keyboard backlight off after inactivity Never
 Keyboard Press fn key Do Nothing
 Trackpad Scroll & Zoom Natural scrolling = DISABLED

Here is some more information explaining the rationale behind some of these System Settings options set:
  1. Use trackpad for scrolling enables scroll bars visible unconditionally + not autohide
  2. Displays have separate Spaces on dual monitors prevents other screen to go black
  3. Displays | Dual Monitors | Ensure resolution is the same default for both monitors
  4. Keyboard | Key repeat rate | Fast ensures that holding key down prevents accents
  5. Trackpad | Natural scrolling Disabled ensures vertical scrolling naturally downward

Keyboard Shortcuts
Customize your general Mac keyboard shortcuts. Launch System Settings | Keyboard | Keyboard Shortcuts:

Here is my quick summary of Keyboard Shortcuts setup that will be compatible with Application navigation:
 Launchpad & Dock Turn Dock hiding on/off DISABLED
 Launchpad & Dock Show Lauchpad DISABLED
 Mission Control Show Desktop [F11] DISABLED
 Mission Control Move left a space [Cmd + left] DISABLED
 Mission Control Move right a space [Cmd + right] DISABLED
 Keyboard Move focus to the window toolbar [Cmd + F5] DISABLED
 Keyboard Move focust to next window [Ctrl + `] ENABLED
 Input Sources Select previous input source [Cmd + Space] DISABLED
 Screenshots Save picture of screen as a file [Ctrl + 3] ENABLED
 Screenshots Save picture of selected area as a file [Ctrl + Shift + 4] ENABLED
 Spotlight Show Spotlight search [Ctrl + Space] DISABLED
 Accessibility Turn VoiceOver on or off [Ctrl + F5] DISABLED
 App Shortcuts All Applications | Rename F2

Here is more information explaining the rationale behind some of these Keyboard Shortcuts... options set:
  1. Disable F11 prevents the Desktop from always showing
  2. Disable Cmd + left prevents move former word collision
  3. Disable Cmd + right prevents move next word collision
  4. Disable Cmd + F5 key prevents IDE debugging collision
  5. Disable Cmd + Space prevents IDE intellisense collision
  6. Disable Ctrl + Space prevents IDE intellisense collision
  7. Disable Ctrl + F5 key prevents Voice Over alternating

The Finder is the home base for your Mac: you use the Finder to organize your folders and files on the Mac. Launch Finder | Settings... Leave all options in Finder Settings but check all checkboxes on Advanced tab:

In View menu check "as Columns" + "Sort By Name". Show all relevant Sidebar, Toolbar, Status options etc:
 View menu | Select the following:
  •  Check "as Columns"
  •  Sort By | Name
  •  Show Sidebar
  •  Show Preview
  •  Show Toolbar
  •  Hide All Tabs
  •  Hide Tab Bar
  •  Show Path Bar
  •  Show Status Bar
  •  Hide View Options
  •  Hide Preview Options

Here are some Windows keyboard shortcut equivalents. *Customization via App Shortcuts as shown below:
 Ctrl + N New Finder Window
 Ctrl + Shift + N New Folder
 Ctrl + O Open File
 Ctrl + Shift + G Go to Folder...
 F2* | Enter Rename File / Folder
 Alt + Backspace Delete File / Folder

Shortcuts: Right click folder | Show in Enclosing folder. Right click folder the Status Bar | Copy as Pathname.

Finally, here are two handy aliases to hide and show private files and folders on Mac via ~/.bash_profile:
 alias showFiles='defaults write AppleShowAllFiles YES; killall Finder   /System/Library/CoreServices/'
 alias hideFiles='defaults write AppleShowAllFiles NO; killall Finder   /System/Library/CoreServices/'

As per this post, Python is installed on most Mac OS/X systems by default. Also, one can install Python when you install Xcode Command Line Tools. Another option is update Python from the official website e.g. v3.12. IMPORTANT: when coding in Python activate the created virtual environment: source .venv/bin/activate.

As per this post, we installed open source Python distribution Anaconda used for data science. However, on the Mac after launch Terminal and enter jupyter notebook you may encounter the following couple errors:

Error #1: Jupyter Notebook 500 : Internal Server Error - follow instructions here to resolve the issue:
 pip install --upgrade jupyterhub
 pip install --upgrade --user nbconvert

Error #2: ModuleNotFoundError: No module named 'jupyter_server.contents' - follow instructions here:
 pip uninstall traitlets
 pip install traitlets==5.9.0
 jupyter notebook

The Mac terminal may be zsh by default. However, change your default shell via Settings... | General | Shell open with: Command path /bin/bash or enter chsh -s /bin/bash. Confirm BASH is now in Terminal title!

IMPORTANT: remove silence deprecation warning | Enter the following into Terminal for ~/.bash_profile:
 echo "export BASH_SILENCE_DEPRECATION_WARNING=1" >> ~/.bash_profile

Customize the Mac terminal to always show full directory path as the cursor similar to the Linux terminal:
 echo "export PS1='\u@\h:\w$ '" >> ~/.bash_profile
Finally, keyboard shortcuts like Ctrl + C or Ctrl + Z may not work to break on Mac thus prefer Ctrl + ".".

Homebrew is a package manager for macOS which lets you install free and open-source software using your terminal. Launch terminal and issue the following commands to install Homebrew and update bash_profile:
 /bin/bash -c "$(curl -fsSL"
 echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile

Install free and open-source software for Cloud Computing for example: minikube, KinD, Helm, Terraform:
 minikube brew install minikube
 KinD brew install kind
 Helm brew install helm
 Terraform brew tap hashicorp/tap | brew install hashicorp/tap/terraform

Cloud CLIs
Download and install Command Line Interfaces for all managed cloud providers e.g.: AWS, Azure, Google: Install the latest version of the AWS CLI. Download the macOS pkg file. Confirm installation aws version. Install Azure CLI on macOS using brew brew update && brew install azure-cli. Confirm install az version. Install the Google Cloud CLI. Download the Apple M1 package. Extract and execute | gcloud init.

As per this post, install Kubernetes with Docker Desktop on Mac OS/X. Next, install and setup kubectl on the Mac OS/X. However, the default kubectl autocomplete setup quick reference may produce the following error
 bash: completion: function `__start_kubectl` not found

If you experience this error then here is an alternative approach: first brew install bash bash-completion Set Terminal to use bash: Settings... | General | Shell open with: Command path /opt/homebrew/bin/bash

Finally, update ~/.bash_profile
 alias k="kubectl"
 complete -F __start_kubectl k
 source /opt/homebrew/etc/profile.d/
 source <(kubectl completion bash)

BASH Profile
Dump out the contents of the ~/.bash_profile file and verify all the following aliases and commands exist:
 export PS1='\u@\h:\w$ ' # Show always fullpath on terminal
 eval "$(/opt/homebrew/bin/brew shellenv)" # brew
 alias d='docker' # Docker
 alias k='kubectl' # Kubernetes
 complete -F __start_kubectl k # Kubernetes autocomplete
 source /opt/homebrew/etc/profile.d/ # Kubernetes autocomplete
 source <(kubectl completion bash) # Kubernetes autocomplete
 alias sba='source .venv/bin/activate' # Python virtual environment
 alias showFiles='defaults write AppleShowAllFiles YES; killall Finder   /System/Library/CoreServices/'
 alias hideFiles='defaults write AppleShowAllFiles NO; killall Finder   /System/Library/CoreServices/'

To summarize, by remapping the modifier keys in System Settings has helped tremendously, however this method does not provide a complete one-to-one mapping for all keyboard shortcuts from Windows to Mac.

Another option is investigate global hotkeys in App Shortcuts for All Applications and specific Applications.

However, this could be extremely time-consuming and unsuccessful thus will keep the setup as is for now. Therefore, he is short list of mismatched keyboard shortcuts going forward and new key combos to learn:
 General Ctrl + H Hide current window of this front app
 General Ctrl + M Minimize all open windows to the Dock
 General Ctrl + 1 Restoring minimized window from Dock
 General Ctrl + ` Move focus to next window of same app
 General Win + Tab Use instead of default Ctrl + Tab option
 Applications Ctrl + Enter Save current open document then exit

After aligning keyboard shortcuts from Windows to Mac the next step is to transfer Application navigation! This will be the topic of the next post.

Monday, January 1, 2024

Retrospective XV

Last year, I conducted a simple retrospective for 2022. Therefore, here is a retrospective for 2023.

2023 Achievements
  • Complete fifteen year blog on agile software application to game development and beyond
  • Enter Lil Evel Knievel in SMS Power! 2023 competition as side scrolling Wonderboy tribute
  • Port Sega Master System games to Sega MegaDrive then document development process
  • Apply Sega Master System development techniques to eBPF setup using C code examples
  • Resurrect test driven development and mock integration into Linux / C environment setup
  • Transition 8-bit Sega Master System development setup to the Nintendo Game Boy+Color
  • Prepare Python environs for OpenAI retro video game Reinforcement Learning integration
  • Experiment with SerenadeAI and prototype ChatGPT APIs across multiple language range

Note: leveraging Sega Master System development setup for Nintendo Game Boy is an achievement!

2024 Objectives
  • Resume Microservices application development and deploy across Distributed Systems at scale
  • Apply Infrastructure as Code and adopt DevOps best practices as software grows in complexity
  • Extend Software Engineering experience across Design + Architectural responsibilities in Cloud
  • Integrate Artificial Intelligence to Software projects: Machine, Deep or Reinforcement Learning

Software architecture plays crucial role in designing + developing effective software systems. Understanding various architectural styles + patterns available, you can make informed decisions in architectural endeavors to create scalable, maintainable, and reliable software solutions. Architectural styles are high-level strategies that provide an abstract framework for a family of systems e.g. Layered, Event-Driven, and Microservices.

Architect Types
Software architects, solution architects and enterprise architects all play a part in designing, developing and implementing solutions that meet the needs of the business but differ with technical, company and IT focus:
 A professional who designs and oversees the development of each software system.
 Ensures that the system meets the needs of the business and is technically feasible.
 A professional who designs and implements solutions that meet needs of the business.
 They have a deep understanding of both the business and the technology landscapes.
 A professional who designs and oversees the overall IT architecture of an organization.
 Ensures architecture aligned with business strategy and supports goals and objectives.

Cloud Variants
Cloud computing is becoming common for accessing data and using appliations in web-based environments. Growing demand for technology solutions in this area request need for cloud architects and cloud engineers:
 A professional who deploys cloud-based applications according to business specifications.
 Architects focus work on the frameworks and infrastructure of cloud-based applications.
 A professional who designs, creates and develops cloud-based systems and solutions.
 Involved in building and testing technical requirements within all these cloud systems.

Microservices have become a game-changer in the quickly changing technological landscape where flexibility, speed and scalability are crucial. Microservices architecture provides a more agile and effective substitute to conventional monolithic techniques and has seen rapidly increasing industry adoption in recent years.

Microservices align seamlessly with DevOps principles, fostering development and operations collaboration for continuous delivery and automation. Microservices architecture also aligns with containerization and orchestration tools like Kubernetes, simplifying the deployment and management of services at scale.

Industry predictions in Microservices expect growth to $1.7b by 2028 as 82% of organizations plan to adopt microservices in the next 3yrs. Microservices are well-suited to leverage emerging technologies such as IoT, edge computing, and blockchain and A.I. has potential to disrupt and innovate in the microservices space.

The Top Tech Skills for 2024 corroborates this as specialization in the cloud computing market is predicted to grow at an annual rate of 18% plus Artificial Intelligence and Machine Learning continue to drive innovations across all industries including using AI in Microservices; AI is becoming an essential part of the microservices ecosystem, enabling businesses to build and maintain large, complex applications more efficiently. It will be interesting to see new innovative ways in which AI may integrate across the Software Engineering spectrum!

Wednesday, November 15, 2023

GBDK Programming Sample

In the previous post, we checked out GBDK Programming Setup. The GBDK is a cross-platform development kit for sm83, z80 and 6502 based gaming consoles including the Nintendo Game Boy and Game Boy Color.

Using the GBDK, it is now possible to write game code using the C language rather than pure Z80 assembly. Therefore, we would like to extend this knowledge and checkout some code samples and homebrew games.

Let's check it out!

Follow all instructions from the previous post: this documents how to setup all the pre-requisite software.
Note: ensure you have downloaded and installed the GBDK devkit and Small Device C Compiler [SDCC].

As per the previous post, after the GBDK has been downloaded, installed and setup, we should now checkout C:\gbdk\examples\gb to learn more about APIs available in the devkit. Replicate prior Hello World example.

Launch Visual Studio 2015. File | New | Project... | Visual C++ | Win32 | Win32 Project
 Name:  Game
 Location:  C:\apa_image
 Create directory for solution  UNCHECKED

Copy over all original folders and files from the corresponding example. Copy from prior Hello World example the hidden .vscode folder and files. Copy also build.bat and align with source compile.bat file. Add relevant files to Visual Studio 2015. Press Ctrl+1 to build, link and run code similar to the prior Hello World example!

Launch Visual Studio Code. Open example folder. Set breakpoint in main.c. Press F5 to debug step thru code

Here is the complete list:
 CUSTOM: apa_image SOURCE: apa_image
 CUSTOM: banks SOURCE: banks
 CUSTOM: bcd SOURCE: bcd
 CUSTOM: colorbar SOURCE: colorbar
 CUSTOM: comm SOURCE: comm
 CUSTOM: crash SOURCE: crash
 CUSTOM: dscan SOURCE: dscan
 CUSTOM: filltest SOURCE: filltest
 CUSTOM: galaxy SOURCE: galaxy
 CUSTOM: gb-dtmf SOURCE: gb-dtmf
 CUSTOM: gbcompress SOURCE: gbcompress
 CUSTOM: incbin SOURCE: incbin
 CUSTOM: irq SOURCE: irq
 CUSTOM: isr_vector SOURCE: isr_vector
 CUSTOM: large_map SOURCE: large_map
 CUSTOM: lcd_isr_wob SOURCE: lcd_isr_wob
 CUSTOM: linkerfile SOURCE: linkerfile
 CUSTOM: metasprites SOURCE: metasprites
 CUSTOM: paint SOURCE: paint
 CUSTOM: ram_function SOURCE: ram_function
 CUSTOM: rand SOURCE: rand
 CUSTOM: rpn SOURCE: rpn
 CUSTOM: scroller SOURCE: scroller
 CUSTOM: sgb_border SOURCE: sgb_border
 CUSTOM: sgb_multiplay SOURCE: sgb_multiplay
 CUSTOM: sgb_pong SOURCE: sgb_pong
 CUSTOM: sgb_sfx SOURCE: sgb_sfx
 CUSTOM: simple_physics SOURCE: simple_physics
 CUSTOM: sound SOURCE: sound
 CUSTOM: temp_minimal SOURCE: temp_minimal
 CUSTOM: temp_subfolder SOURCE: temp_subfolder
 CUSTOM: wav_sample SOURCE: wav_sample

Gaming Monsters YouTube channel has many samples to teach how to develop your own GameBoy games:

Launch Visual Studio 2015. File | New | Project... | Visual C++ | Win32 | Win32 Project
 Name:  Game
 Location:  C:\SimpleSprites
 Create directory for solution  UNCHECKED

Copy over all original folders and files from the corresponding example. Copy from prior Hello World example the hidden .vscode folder and files. Copy also build.bat and align with source's make.bat file. Add relevant files to Visual Studio 2015. Press Ctrl+1 to build, link and run code similar to the prior Hello World example!

Launch Visual Studio Code. Open example folder. Set breakpoint in main.c. Press F5 to debug step thru code

Here is the complete list:
 CUSTOM: helloworld SOURCE: helloworld
 CUSTOM: simplesprites SOURCE: simplesprites
 CUSTOM: movesprites SOURCE: movesprites
 CUSTOM: background SOURCE: background
 CUSTOM: window SOURCE: window
 CUSTOM: sound SOURCE: sound
 CUSTOM: noise SOURCE: noise
 CUSTOM: simplejumping SOURCE: simplejumping
 CUSTOM: metasprites SOURCE: metasprites
 CUSTOM: spritecollision SOURCE: spritecollision
 CUSTOM: bkgdcollision SOURCE: bkgdcollision
 CUSTOM: splashscreens SOURCE: splashscreens
 CUSTOM: fadeeffects SOURCE: fadeeffects
 CUSTOM: keyboard SOURCE: keyboard
 CUSTOM: savename SOURCE: savename
 CUSTOM: colorsprites SOURCE: colorsprites
 CUSTOM: backgrounds SOURCE: backgrounds
 CUSTOM: makingmusic SOURCE: makingmusic
 CUSTOM: spritetricks SOURCE: spritetricks
 CUSTOM: scrolling SOURCE: scrolling
 CUSTOM: debugging SOURCE: debugging
 CUSTOM: platformer SOURCE: platformer

Larold's Jubilant Junkyard is a website/blog/shop which focuses on creating digital products including game development projects and tutorials. The Nintendo GameBoy development tutorial series is very educational.

Follow Larold's Jubilant Junkyard YouTube video channel for additional GBDK 2020 information and content:
 SCREEN resolution  20 x 18 tiles  160 x 144 pixels
 BACKGROUND  32 x 32 tiles  256 x 256 pixels

Compiler flags
 -Wm-yc  GameBoy Color compatible  NB: lowercase c
 -Wm-yC  GameBoy Color only  NB: lowercase C
 -Wm-ys  Super GameBoy compatible  

GameBoy Color Tile Attributes
 Bit 7  priority flag  0: tiles below sprites, 1: tiles above sprites
 Bit 6  vertical flip  0: tiles normal, 1: flipped vertically
 Bit 5  horizontal flip  0: tiles normal, 1: flipped horizontally
 Bit 4  not used  
 Bit 3  character bank specification  0: tiles at bank0, 1: tiles at bank1
 Bit 2  see bit 0  
 Bit 1  see bit 0  
 Bit 0  bits 0-2  indicate tile color palette assignment

Launch Visual Studio 2015. File | New | Project... | Visual C++ | Win32 | Win32 Project
 Name:  Game
 Location:  C:\AlleywayGameboy
 Create directory for solution  UNCHECKED

Copy over all original folders and files from the corresponding example. Copy from prior Hello World example the hidden .vscode folder and files. Copy also build.bat and align with source's make.bat file. Add relevant files to Visual Studio 2015. Press Ctrl+1 to build, link and run code similar to the prior Hello World example!

NOTE: ensure that the GBDK header files are included for Intellisense: Right click project | Properties |
Configuration Properties | C/C++ | General | Additional Include Directories | %GBDK_WIN%/include; $(SolutionDir)/headers/gen; $(SolutionDir)/headers/main; %(AdditionalIncludeDirectories).

Here is the complete list:
 CUSTOM: alleyway  SOURCE: alleyway
 CUSTOM: flappy-bird  SOURCE: flappy-bird
 CUSTOM: pacman  SOURCE: pacman
 CUSTOM: space-invaders  SOURCE: space-invaders

Armed with all this knowledge, we are now in an excellent position to build complete video games for the Nintendo Game Boy and Game Boy Color. In the interim, we see the GameBoy Competition 2023 is here!