document.tex

\documentclass[14pt,a4paper]{extarticle}
% \documentclass[a4paper]{article}
\usepackage[a4paper,left=1in,right=1in,top=1in,bottom=1in]{geometry}
\usepackage[colorlinks=true, linkcolor=blue, citecolor=, urlcolor=blue]{hyperref}
\usepackage{float}
\usepackage[parfill]{parskip}
\usepackage{caption}


% ---------- Font (Thai: Angsana New 14pt) ----------
\usepackage{fontspec}
\XeTeXlinebreaklocale "th"
% \XeTeXlinebreakskip = 0pt plus 1pt
\setmainfont{TH Sarabun New}
\setmonofont{JetBrains Mono}[Scale=MatchLowercase]

\usepackage{listings}
\usepackage{xcolor}
\usepackage[most]{tcolorbox}
\tcbuselibrary{listings, skins}

% GitHub / VitePress Theme Colors
\definecolor{codebg}{HTML}{F6F8FA}
\definecolor{codeframe}{HTML}{D0D7DE}
\definecolor{codetext}{HTML}{24292F}
\definecolor{codekeyword}{HTML}{CF222E}
\definecolor{codecomment}{HTML}{6E7781}
\definecolor{codestring}{HTML}{0A3069}
\definecolor{codelinenum}{HTML}{8C959F}

% Listings base styling
\lstdefinestyle{githubstyle}{
    basicstyle=\ttfamily\small\color{codetext},
    keywordstyle=\color{codekeyword}\bfseries,
    commentstyle=\color{codecomment}\itshape,
    stringstyle=\color{codestring},
    breaklines=true,
    breakatwhitespace=false,
    tabsize=4,
    showstringspaces=false,
    numbers=left,
    numberstyle=\tiny\color{codelinenum},
    numbersep=8pt,
    xleftmargin=10pt,
}

% ----------------------------------------------------
% 1. Inline Code: \code{...} or \code|...|
% ----------------------------------------------------
\DeclareTotalTCBox{\code}{ v }{
    on line,
    arc=3.5pt,
    boxrule=0.5pt,
    colback=codebg,
    colframe=codeframe,
    boxsep=0pt,
    left=3.5pt,
    right=3.5pt,
    top=1.5pt,
    bottom=1.5pt,
    fontupper=\ttfamily\color{codetext},
}{#1}

% ----------------------------------------------------
% 2. Multi-line Code Block: \begin{codeblock}[<language>]
% ----------------------------------------------------
\newtcblisting{codeblock}[1][]{
    enhanced,
    arc=5pt,
    boxrule=0.5pt,
    colback=codebg,
    colframe=codeframe,
    boxsep=0pt,
    top=8pt,
    bottom=8pt,
    left=4pt,
    right=8pt,
    listing only,
    listing engine=listings,
    listing options={
        style=githubstyle,
        language=#1,
    }
}

% Language-specific convenience shortcuts
\newtcblisting{javacode}[1][]{
    enhanced,
    arc=5pt,
    boxrule=0.5pt,
    colback=codebg,
    colframe=codeframe,
    boxsep=0pt,
    top=8pt,
    bottom=8pt,
    left=4pt,
    right=8pt,
    listing only,
    listing engine=listings,
    listing options={
        style=githubstyle,
        language=Java,
        #1
    }
}

\newtcblisting{bashcode}[1][]{
    enhanced,
    arc=5pt,
    boxrule=0.5pt,
    colback=codebg,
    colframe=codeframe,
    boxsep=0pt,
    top=8pt,
    bottom=8pt,
    left=4pt,
    right=8pt,
    listing only,
    listing engine=listings,
    listing options={
        style=githubstyle,
        language=bash,
        #1
    }
}

\usepackage{fancyvrb}

% Define a custom environment with zero extra line skip
\DefineVerbatimEnvironment{TightVerbatim}{Verbatim}{
%   formatcom=\setlength{\lineskip}{0pt},
  formatcom={\baselineskip=-\maxdimen\lineskip=0pt}
%   baselinestretch=0.8 % adjust multiplier as needed
}



\title{วิธี Setup เครื่องมือที่ใช้ในวิชา}
% \author{TA Omsin}
\date{Updated \today}

\begin{document}
\maketitle
\tableofcontents
\newpage

\section{What does each tool do?}

ในวิชานี้ เราจะใช้เครื่องมือพวกนี้
\begin{enumerate}
    \item {\textbf{JDK 25}}: เพื่อ compile และ run Java
    \item {\textbf{JavaFX}}: เพื่อรันโปรเจคที่ใช้ JavaFX (ใน lab หลังๆ)
    \item \textbf{IntelliJ IDEA}: โปรแกรมที่มีชุดเครื่องมือต่างๆสำหรับเขียนภาษา Java
    \item \textbf{Gradle (9.1.0+)}: build tools สำหรับ Java
    \item \textbf{PlantUML extension}: ใช้ generate UML diagram จาก code
    \item \textbf{Git}: เป็นโปรแกรมประเภท "version control" ที่นิยมใช้
\end{enumerate}

\section{How to setup/install each tool?}

\subsection{JDK 25}
% JDK vs JRE
JDK (Java Development Kit) เป็นชุดเครื่องมือสำหรับ compile และ run Java สำหรับเทอมนี้ให้ใช้ JDK เวอร์ชัน 25 เพราะว่าเป็นเวอร์ชันล่าสุดที่เป็น LTS (Long-Term Support)

ข้างล่างนี้เป็นวิธีติดตั้ง JDK 25 จาก Adoptium Temurin แต่จริงๆใช้ของเจ้าไหนก็ได้ ขอให้เป็นเวอร์ชัน 25 ก็พอ

\subsubsection{Setup (Windows)}
\begin{enumerate}
    \item ไปที่ \href{https://adoptium.net/temurin/releases?version=25&os=windows&arch=any}{https://adoptium.net/temurin/releases?version=25\&os=windows\&arch=any}
    \item เลือก ``JDK'' แล้วกดปุ่ม download (see image below)
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.8\textwidth]{assets/jdk/temurin-download.png}
          \end{figure}
    \item รันตัว installer แล้วกดไปเรื่อยๆจนถึงหน้า ``Custom Setup''
    \item ในหน้า ``Custom Setup'' ให้ปรับ ``Set or override JAVA\_HOME variable'' จากเดิมที่เป็นกากบาทให้เป็น ``Will be installed on local hard drive'' (see image below)
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.6\textwidth]{assets/jdk/javahome-2-annotated.png}
          \end{figure}
    \item กดยืนยันต่อไปเรื่อยๆจนจบ
    \item ถ้าเปิด terminal ไว้อยู่ให้ปิดแล้วเปิดใหม่ก่อน มันถึงจะหา \code{java} เจอ
    \item เช็คว่าติดตั้งสำเร็จได้ด้วยการรัน \code{java --version} ใน terminal
\end{enumerate}

\subsubsection{Setup (macOS)}
\begin{enumerate}
    \item แนะนำให้ลงผ่าน \hyperref[sec:homebrew]{Homebrew} โดยรันคำสั่ง \code{brew install temurin@25} ใน terminal
          % should I mention installer approach for macos as well?
    \item เช็คว่าติดตั้งสำเร็จได้ด้วยการรัน \code{java --version} ใน terminal (อาจจะต้องปิด terminal เปิดใหม่ก่อน ไม่มั่นใจ)
\end{enumerate}
\subsubsection{Setup (Linux)}
\begin{enumerate}
    \item ลงผ่าน package manager (อาจต้องเพิ่ม apt repo ก่อนสำหรับ Debian-based ลองอ่านเพิ่มเติมได้ที่ \href{https://adoptium.net/installation}{https://adoptium.net/installation}) \underline{\textbf{อย่าลืมว่าเราใช้เวอร์ชัน 25}}
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.6\textwidth]{assets/jdk/linux.png}
          \end{figure}
\end{enumerate}

\subsection{JavaFX}
เพื่อให้รัน jar ที่ใช้ JavaFX นอก Gradle ได้ (การรันด้วย \code{java -jar ...}) เราจะต้องโหลด JavaFX SDK มาต่างหากด้วย (จริงๆมีอีกวิธีคือเรา bundle ตัว JavaFX ไปใน jar file แต่เราจะไม่ใช้ในวิชานี้)


\subsubsection{Setup}
\begin{enumerate}
    \item Download JavaFX SDK (เวอร์ชัน 25.0.4) จาก \href{https://gluonhq.com/products/javafx/}{Gluon}
          \begin{itemize}
              \item \textbf{Windows (x64)} \href{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4_windows-x64_bin-sdk.zip}{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4\_windows-x64\_bin-sdk.zip}
              \item \textbf{Linux (x64)} \href{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4_linux-x64_bin-sdk.zip}{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4\_linux-x64\_bin-sdk.zip}
              \item \textbf{macOS (x64)} \href{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4_osx-x64_bin-sdk.zip}{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4\_osx-x64\_bin-sdk.zip}
              \item \textbf{macOS (aarch64)} \href{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4_osx-aarch64_bin-sdk.zip}{https://download2.gluonhq.com/openjfx/25.0.4/openjfx-25.0.4\_osx-aarch64\_bin-sdk.zip}
          \end{itemize}
    \item Unzip ไฟล์ที่เพิ่ง download มา จะได้ folder ชื่อว่า \code{javafx-sdk-25.0.4}
    \item เอา folder นั้นไปไว้ที่ไหนก็ได้ (จำไว้ด้วยว่าเอาไปไว้ที่ไหน) สำหรับตัวอย่างนี้เราจะไว้ที่\\ \code{/home/myuser/javafx-sdk-25.0.4/}
    \item จำไว้ว่าให้ใช้ตำแหน่งนี้ต่อท้ายด้วย \code{/lib} เป็น \code{module-path} สำหรับรันคำสั่ง \code{java -jar ...} กับโปรเจคที่ใช้ JavaFX เช่น ``java -jar --module-path /home/myuser/javafx-sdk-25.0.4/lib --add-modules javafx.fxml,javafx.controls my-program.jar'' \\
          \textit{\textbf{รายละเอียดการใช้งานดูได้ใน slide JavaFX บน myCourseVille}}
\end{enumerate}

\subsection{IntelliJ IDEA}
เป็น IDE (โปรแกรมที่เอาไว้เขียนโปรแกรม) สำหรับ Java ที่ popular ตัวนึง ที่เราจะใช้ในวิชานี้
\subsubsection{Setup}
\begin{enumerate}
    \item ไปที่ \href{https://www.jetbrains.com/idea/download/}{https://www.jetbrains.com/idea/download/} แล้วเลือกโหลดตาม OS และ architecture ของตัวเอง
    \item รัน installer และติดตั้งตามปกติ ใช้ค่า default ที่มันให้มาได้เลย
\end{enumerate}

\subsubsection{How to start a new project?}\label{sec:new_project}
\begin{enumerate}
    \item เปิด New Project
          \begin{itemize}
              \item ถ้าเปิดโปรเจคอยู่แล้วให้เลือก ``File'' ใน menu bar แล้วเลือก ``New Project''
              \item ถ้าขึ้น start dialog ก็แค่เลือกปุ่ม ``New Project''
          \end{itemize}
    \item (ดูภาพด้านล่าง) ให้มั่นใจว่าเลือก option ตามนี้:
          \begin{itemize}
              \item Build system เป็น ``Gradle''
              \item JDK เป็นเวอร์ชัน 25
              \item Gradle DSL เป็น Kotlin
              \item Gradle version เป็น 9.x.x หรือไม่ก็เปิด ``Auto select'' (สำหรับสอบอาจจะเป็นเวอร์ชันอื่น ถ้าเปลี่ยนจะบอกอีกที)
          \end{itemize}
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.6\textwidth]{assets/intellij/new_project_annotated-2.png}
          \end{figure}
    \item กดปุ่ม ``Create''
\end{enumerate}
\textit{\textbf{รายละเอียดเพิ่มเติมและการส่งงานโดยใช้ Git ดูได้ที่ ``How to start lab 1'' หน้า 5 เป็นต้นไปบน myCourseVille}}

\subsection{Gradle}
ถ้าคุณใช้ IntelliJ IDEA เพียงแค่คุณมี \code{build.gradle.kts} และ \code{settings.gradle.kts} (ที่แจกให้ในไฟล์ zip ของแต่ละ lab) อยู่ใน project folder ก็พอ แล้วตัว IntelliJ จะ detect และโหลด Gradle ให้เอง

อย่างไรก็ตาม เวลาเราใช้ Gradle มันจะ expect ให้ folder structure ของโปรเจคมีรูปแบบที่เฉพาะของมัน เพราะฉะนั้นเวลาสร้าง project ใหม่\underline{\textbf{ต้อง make sure ด้วยว่า}}
\begin{enumerate}
    \item มี \code{build.gradle.kts} และ \code{settings.gradle.kts} อยู่ใน project folder และ ได้ใช้อันที่แจกให้
          \footnote{จำเป็นต้องใช้ build.gradle.kts และ settings.gradle.kts ที่แจกให้ เพราะว่ามีการปรับให้ include source เข้าไปใน jar ด้วย ซึ่งโดย default มันไม่ทำ ถ้า jar ที่คุณส่งมาไม่มี source อาจจะถูกหักคะแนนตามเกณฑ์ที่ประกาศสำหรับแต่ละ lab}
    \item ได้เลือก Build system เป็น ``Gradle'' ตามที่เขียนใน section \ref{sec:new_project} (วิธีสร้าง project ใน IntelliJ)
    \item ใน \code{build.gradle.kts} ตั้ง main class ไว้ถูก เช่น
          %           \begin{javacode}
          % application {
          %     // Ex. "src/main/java/game/DeckManager.java" becomes "game.Deckmanager"
          %     mainClass.set("game.DeckManager")
          % }
          %           \end{javacode}
    \item มี project structure ที่ถูกต้อง:
          \VerbatimInput[formatcom=\setlength{\lineskip}{0pt}]{project_structure.txt}
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.4\textwidth]{assets/gradle/sample_structure.png}
              \caption*{ตัวอย่าง project ที่ structure ถูกต้องตามที่ Gradle ต้องการ}
          \end{figure}
\end{enumerate}
\subsubsection{How to use Gradle?}
หนึ่งใน feature ของ Gradle คือมันมีระบบ task เป็นเหมือนชุดคำสั่งอำนวยความสะดวกให้เราเรียกใช้งานได้
ใน IntelliJ ให้กดเปิดแถบด้านขวาที่เป็นรูปช้างมา (ดูภาพด้านล่าง)
คุณจะเห็น task ต่างๆที่มีประโยชน์กับ project ภาษา Java
\begin{figure}[H]
    \centering
    \includegraphics[width=0.2\textwidth]{assets/gradle/menu.png}
\end{figure}

สำหรับวิชานี้เราใช้อยู่ๆหลักๆ 4 tasks (ไม่ได้ห้ามที่จะ explore feature หรือ task อื่นๆนะ)
\begin{figure}[H]
    \centering
    \includegraphics[width=0.4\textwidth]{assets/gradle/tasks.png}
\end{figure}
\begin{itemize}
    \item \code{run} ใช้สำหรับ run program (ไม่ได้สร้าง jar ให้นะ รันเฉยๆ)
    \item \code{build} ทำทุกอย่างเพื่อให้ได้ jar file ออกมา (compile -> test -> สร้าง jar) ปกติเวลาสร้าง jar file แนะนำให้ใช้ task นี้
    \item \code{jar} เหมือน \code{build} แต่ไม่รัน test (กรณีนึงคือใช้แทน \code{build} เวลาอยากสร้าง jar file แต่ test รันไม่ผ่าน)
    \item \code{test} รัน unit test
\end{itemize}
สังเกตว่า build มันมาเรียก test ได้ด้วย เพราะ Gradle tasks รองรับการมี dependency (task นึงไปเรียกอีก task ได้)
รายละเอียดดูได้จากในภาพ (ให้ดูเป็นข้อมูลเฉยๆ ไม่ต้องจำก็ได้)
\begin{figure}[H]
    \centering
    \includegraphics[width=\textwidth]{assets/gradle/deps.png}
    \caption*{Task dependencies ของ Java (จาก \href{https://docs.gradle.org/current/userguide/java_plugin.html}{official doc})}
\end{figure}

\subsection{PlantUML}
จริงๆตัว PlantUML มีวิธีติดตั้งและใช้งานหลายแบบ สำหรับวิชานี้เราลง\underline{เป็น extension บน IntelliJ IDEA}

\subsubsection{Setup (Windows)}
\begin{enumerate}
    \item เปิด IntelliJ IDEA
    \item ไปที่ตั้งค่า plugins
          \begin{itemize}
              \item ถ้าเปิด project อยู่ ให้ไปที่มุมบนขวาของจอแบบในรูปด้านล่าง
                    \begin{figure}[H]
                        \centering
                        \includegraphics[width=0.6\textwidth]{assets/plantuml/plugin-menu-project.png}
                    \end{figure}
              \item ถ้าขึ้น start window ให้ไปที่แถบ Plugin แบบในรูปด้านล่าง
                    \begin{figure}[H]
                        \centering
                        \includegraphics[width=0.6\textwidth]{assets/plantuml/plugin-menu-start.png}
                    \end{figure}
          \end{itemize}
    \item search ว่า ``plantuml'' และ install plugin ชื่อ ``plantuml4idea'' และ ``PlantUML Parser''
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.6\textwidth]{assets/plantuml/plantuml-plugins.png}
          \end{figure}
\end{enumerate}
\subsubsection{Setup (macOS \& Linux)}
\begin{enumerate}
    \item ทำเหมือนกับ Windows
    \item ลง graphviz
          \begin{itemize}
              \item macOS แนะนำให้ลงผ่าน \hyperref[sec:homebrew]{Homebrew} โดยรันคำสั่ง \code{brew install graphviz} ใน terminal
              \item Linux ลงผ่าน package manager ตามปกติ (ปกติ package ก็ชื่อ graphviz นี่แหละ)
          \end{itemize}

\end{enumerate}

\subsubsection{How to generate a UML diagram?}
\begin{enumerate}
    \item เลือกคลุม class ที่ต้องการจะสร้าง diagram ในแถบดูไฟล์ (เลือกได้หลาย class พร้อมๆกัน)
    \item คลิกขวาแล้วเลือก ``PlantUML Parser'' (see image below)
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.4\textwidth]{assets/plantuml/parser_dialog.png}
          \end{figure}
    \item จากนั้นจะมีหน้า config ขึ้นมา ให้แก้ไข config ตามนี้ (see image below)
          \begin{itemize}
              \item File Name ปรับเป็น ``UML''
              \item ติ๊กเลือก ``constructors''
              \item Language Level ปรับเป็น JAVA\_17
          \end{itemize}
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.8\textwidth]{assets/plantuml/parserconfig.png}
          \end{figure}
    \item กด ``Generate''
    \item จากนั้นมันจะขึ้น tab ที่เป็น puml กับภาพ diagram มา ให้คลิกขวาฝั่งที่เป็น diagram แล้วเลือก ``Save Diagram'' (see image below)
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.8\textwidth]{assets/plantuml/sidebyside.png}
          \end{figure}
    \item บน dialog ที่ขึ้นมาหลังจากนั้น ให้ save เป็น png และเอาไปวางไว้ที่ \code{src/main/resources} ใน project นี้ (จะได้ไฟล์ชื่อ UML.png)
\end{enumerate}
\textit{\textbf{อ่านรายละเอียดเกี่ยวกับ UML ได้ที่ ``Lecture 1 UML'' บน myCourseVille}}

\subsection{Git}
\subsubsection{Setup (Windows)}
\begin{enumerate}
    \item ไปที่ \href{https://git-scm.com/install/windows}{https://git-scm.com/install/windows}
    \item กด Download ตรงที่ระบุในภาพด้านล่าง (มันจะเลือก installer สำหรับ architecture ของคุณให้เอง)
          \begin{figure}[H]
              \centering
              \includegraphics[width=0.6\textwidth]{assets/git/windows.png}
          \end{figure}
    \item รัน installer แล้วคลิก ``Next'' ไปเรื่อยๆ จนติดตั้งสำเร็จ (ใช้ค่า default ที่มันให้มาได้เลย ไม่จำเป็นต้องแก้อะไร)
    \item ถ้าเปิด terminal ไว้อยู่ให้ปิดแล้วเปิดใหม่ก่อน มันถึงจะหา \code{git} เจอ
    \item เช็คว่าติดตั้งสำเร็จได้ด้วยการรัน \code{git --version} ใน terminal
\end{enumerate}

\subsubsection{Setup (macOS)}
มี git มากับระบบอยู่แล้ว \underline{ใช้ตัวนั้นได้เลย} แต่มันไม่ได้เป็น version ล่าสุด ถ้าใครอยากจะเอา git ที่ version ล่าสุดให้ลงผ่าน \hyperref[sec:homebrew]{Homebrew} \code{brew install git}
**ย้ำอีกที ไม่ได้จำเป็นต้องลงซ้ำนะ**
\subsubsection{Setup (Linux)}
distro ส่วนใหญ่น่าจะลงมาให้แล้ว ถ้าไม่ก็ลงผ่าน package manager


\section{Extra stuff}
ส่วนนี้ไม่เกี่ยวกับเนื้อหาหรือเครื่องมือของวิชานี้โดยตรง แต่ผมคิดว่าในเมื่อมาสายนี้แล้วรู้ไว้ก็ดี
\subsection{Homebrew}
\label{sec:homebrew}
เป็น package manager ที่ popular ในหมู่คนใช้ macOS \\
หลายๆ เครื่องมือที่ใช้ใน software development มันลงผ่าน Homebrew ง่ายมาก (มักจะแค่รันคำสั่ง \\ \code{brew install <package_name>})
เพราะฉะนั้นถ้าใครใช้ macOS แล้วยังไม่รู้จัก Homebrew ผมก็แนะนำให้ลองไปศึกษาดู

\textbf{Installation:} รัน script ที่เขาแปะไว้ใน official website เลย

\textbf{Official website:} \href{https://brew.sh/}{https://brew.sh/}

แล้วก็มี alternative นึงที่ popular พอๆกันชื่อ \href{https://www.macports.org/}{MacPorts} เผื่อใครสนใจ

\newpage
\section*{References}

\begin{itemize}
    \item More detail about UML and PlantUML in ``Lecture 1 UML'' on mCV
    \item More on IntelliJ project creation in ``How to start lab 1'' on mCV
    \item (outdated) Previous revision: ``Gradle Sample Project Setup'' on mCV
\end{itemize}

\end{document}