Project configuration

منصة	أمر
Ubuntu/Debian	`sudo apt update && sudo apt install ant`
RHEL/CentOS/Fedora	`sudo yum install ant` or `sudo dnf install ant`
Arch Linux	`sudo pacman -S apache-ant`
macOS (Homebrew)	`brew install ant`
Windows (Chocolatey)	`choco install ant`
Manual (All Platforms)	Download from apache.org, extract, set `ANT_HOME` and add `bin/` to `PATH`
`JAVA_HOME`## التثبيت

أمر	وصف
`ant -version`	عرض إصدار Ant، وإصدار Java، ومعلومات نظام التشغيل
`ant`	نفّذ الهدف الافتراضي المحدد في build.xml
`ant compile`	قم بتشغيل هدف “compile” من ملف build.xml
`ant clean`	قم بتشغيل الهدف “clean” (عادة ما يزيل بقايا البناء)
`ant -projecthelp`	اسرد جميع الأهداف المتاحة مع الوصف
`ant -p`	اختصار لـ -projecthelp
`ant -f custom-build.xml`	استخدم ملف بناء بديل بدلاً من build.xml
`ant -buildfile mybuild.xml compile`	حدد ملف البناء والهدف للتنفيذ
`ant -verbose compile`	عرض معلومات التنفيذ التفصيلية
`ant -v test`	اختصار لـ -verbose
`ant -debug package`	الحد الأقصى من التفصيل للتحري عن الأخطاء
`ant -d deploy`	اختصار -debug
`ant -quiet test`	قواعد:

إخراج أدنى، إظهار الأخطاء فقط | | ant -q build | اختصار كلمة -quiet | | ant -logfile build.log compile | توجيه المخرجات إلى ملف سجل محدد | | ant -l output.log test | -log |المتطلبات الأساسية: مطلوب Java JDK 8+. قم بتعيين | أمر | وصف | |---------|-------------| | ant -Denv=production deploy | تعيين قيمة الخاصية من سطر الأوامر | | ant -Dversion=1.2.3 -Dbuild.number=456 package | تعيين خصائص متعددة | | ant -propertyfile custom.properties build | تحميل الخصائص من ملف خارجي | | ant -find | ابحث في الدلائل الأصلية عن build.xml | | ant -s | اختصار لـ -find | | ant -keep-going test | استمر في تنفيذ الأهداف المستقلة بعد الفشل | | ant -k test | اختصار keep-going | | ant -diagnostics | عرض معلومات النظام وتفاصيل التكوين | | ant -listener org.apache.tools.ant.listener.Log4jListener compile | أضف مستمع حدث بناء مخصص | | ant -logger org.apache.tools.ant.NoBannerLogger compile | استخدم تطبيق مسجل الأحداث (logger) مخصص | | ant -inputhandler org.apache.tools.ant.input.SecureInputHandler deploy | استخدم معالج إدخال مخصص للإدخال الآمن | | ant -noclasspath compile | تجاهل متغير البيئة CLASSPATH | | ant -autoproxy download | إعداد إعدادات بروكسي Java تلقائيًا | | ant -lib /path/to/jars compile | أضف دليل JARs إلى مسار الفئة الخاص بـ Ant | | ant -Dant.executor.class=org.apache.tools.ant.helper.ParallelExecutor build | تمكين التنفيذ المتوازي للمهام | | ant compile test package | تنفيذ أهداف متعددة بشكل متتابع | | ant -Dskip.tests=true package | تخطي المهام بشكل شرطي بناءً على خاصية |متغير البيئة.

<?xml version="1.0" encoding="UTF-8"?>
<project name="MyProject" default="build" basedir=".">
    
    <!-- Properties -->
    <property name="src.dir" value="src"/>
    <property name="build.dir" value="build"/>
    <property name="dist.dir" value="dist"/>
    <property name="lib.dir" value="lib"/>
    
    <!-- Classpath -->
    <path id="classpath">
        <fileset dir="${lib.dir}">
            <include name="**/*.jar"/>
        </fileset>
    </path>
    
    <!-- Clean target -->
    <target name="clean" description="Remove build artifacts">
        <delete dir="${build.dir}"/>
        <delete dir="${dist.dir}"/>
    </target>
    
    <!-- Init target -->
    <target name="init" depends="clean">
        <mkdir dir="${build.dir}"/>
        <mkdir dir="${dist.dir}"/>
    </target>
    
    <!-- Compile target -->
    <target name="compile" depends="init" description="Compile source code">
        <javac srcdir="${src.dir}" 
               destdir="${build.dir}"
               classpathref="classpath"
               includeantruntime="false"
               debug="true"
               source="11"
               target="11"/>
    </target>
    
    <!-- Build target -->
    <target name="build" depends="compile" description="Build JAR file">
        <jar destfile="${dist.dir}/${ant.project.name}.jar" 
             basedir="${build.dir}">
            <manifest>
                <attribute name="Main-Class" value="com.example.Main"/>
            </manifest>
        </jar>
    </target>
    
</project>
```## الأوامر الأساسية
```properties
# Project configuration
project.name=MyApplication
project.version=1.0.0

# Directory structure
src.dir=src/main/java
test.dir=src/test/java
resources.dir=src/main/resources
build.dir=target/classes
dist.dir=dist

# Compiler settings
java.source.version=11
java.target.version=11
javac.debug=true
javac.deprecation=true

# Dependencies
lib.dir=lib
```## الاستخدام المتقدم
```xml
<property file="build.properties"/>
<property file="build-${env}.properties"/>
<property environment="env"/>
```## الإعدادات
```xml
<!-- Include all Java files -->
<fileset dir="${src.dir}" includes="**/*.java"/>

<!-- Exclude test files -->
<fileset dir="${src.dir}">
    <include name="**/*.java"/>
    <exclude name="**/*Test.java"/>
</fileset>

<!-- Pattern sets for reuse -->
<patternset id="source.patterns">
    <include name="**/*.java"/>
    <include name="**/*.properties"/>
    <exclude name="**/*Test.java"/>
</patternset>
```### الهيكل الأساسي لـ build.xml
```bash
# Clean previous builds
ant clean

# Compile, test, and package in one command
ant compile test package

# Build with specific environment properties
ant -Denv=production -propertyfile prod.properties package

# Create distribution with documentation
ant clean compile test package javadoc dist

<target name="test" depends="compile">
    <junit printsummary="yes" haltonfailure="yes">
        <classpath>
            <path refid="classpath"/>
            <pathelement location="${build.dir}"/>
        </classpath>
        <batchtest fork="yes">
            <fileset dir="${test.dir}">
                <include name="**/*Test.java"/>
            </fileset>
        </batchtest>
    </junit>
</target>

<target name="javadoc">
    <javadoc sourcepath="${src.dir}" 
             destdir="${dist.dir}/docs"
             packagenames="com.example.*"/>
</target>
```### ملف build.properties
```bash
# Build and package web application
ant clean compile war

# Deploy to application server
ant -Dserver.path=/opt/tomcat/webapps deploy

<target name="war" depends="compile">
    <war destfile="${dist.dir}/${project.name}.war" 
         webxml="web/WEB-INF/web.xml">
        <classes dir="${build.dir}"/>
        <lib dir="${lib.dir}"/>
        <fileset dir="web">
            <include name="**/*.jsp"/>
            <include name="**/*.html"/>
            <include name="**/*.css"/>
            <include name="**/*.js"/>
        </fileset>
    </war>
</target>

<target name="deploy" depends="war">
    <copy file="${dist.dir}/${project.name}.war" 
          todir="${server.path}"/>
</target>
```### تحميل الخصائص في build.xml
```bash
# Build all modules in parallel
ant -Dant.executor.class=org.apache.tools.ant.helper.ParallelExecutor build-all

# Build specific module
ant -Dmodule=core build-module

# Build and run integration tests
ant build-all integration-test

<target name="build-all">
    <subant target="build">
        <fileset dir="." includes="*/build.xml"/>
    </subant>
</target>

<target name="build-module">
    <ant dir="${module}" target="build" inheritAll="false"/>
</target>
```### مجموعات الملفات والأنماط الشائعة
```bash
# Skip tests during build
ant -Dskip.tests=true package

# Build only if sources changed
ant -Dincremental=true compile

# Production build with optimizations
ant -Doptimize=true -Ddebug=false production-build

<target name="compile">
    <javac srcdir="${src.dir}" 
           destdir="${build.dir}"
           debug="${debug}"
           optimize="${optimize}">
        <classpath refid="classpath"/>
    </javac>
</target>

<target name="test" unless="skip.tests">
    <junit printsummary="yes">
        <classpath>
            <path refid="classpath"/>
            <pathelement location="${build.dir}"/>
        </classpath>
        <batchtest>
            <fileset dir="${test.dir}" includes="**/*Test.java"/>
        </batchtest>
    </junit>
</target>

<target name="package" depends="compile,test">
    <jar destfile="${dist.dir}/${ant.project.name}.jar" 
         basedir="${build.dir}"/>
</target>
```## حالات الاستخدام الشائعة
```bash
# Run database migrations
ant -propertyfile db-config.properties db-migrate

# Deploy application with database updates
ant -Denv=staging db-migrate deploy

# Rollback database changes
ant -Dversion=1.2.0 db-rollback
```### حالة الاستخدام: بناء تطبيق Java كامل
```xml
<target name="db-migrate">
    <sql driver="${db.driver}"
         url="${db.url}"
         userid="${db.user}"
         password="${db.password}"
         src="migrations/migrate-${version}.sql"
         print="yes"
         output="migration.log"/>
</target>

<target name="db-rollback">
    <sql driver="${db.driver}"
         url="${db.url}"
         userid="${db.user}"
         password="${db.password}"
         src="migrations/rollback-${version}.sql"/>
</target>

` to keep build.xml clean and reusable.

Define meaningful target descriptions: Add الوصف attributes to public targets for better ant -projecthelp output. This serves as built-in documentation for your build process.
Leverage target dependencies: Use يعتمد attribute to establish build order and avoid redundant task execution. Ant automatically handles dependency resolution.
Set includeantruntime="false" in javac tasks: Prevents Ant runtime libraries from polluting your application classpath, avoiding potential conflicts and reducing JAR size.
Use filesets and pattern sets for flexibility: Define reusable file patterns with <مجموعة_النمط> and reference them in multiple targets. This makes maintenance easier and reduces duplication.
Implement incremental builds: Use <حتى_التاريخ> conditions to skip compilation when source files haven’t changed, significantly speeding up development builds.
Version control your build files: Include build.xml, property files, and custom tasks in version control. Exclude generated directories like build/ and dist/ using .gitignore.
Use macros for repeated task sequences: Define <تعريف_ماكرو> elements for common operations performed across multiple modules or targets, promoting DRY principles.
Separate concerns with imported build files: Split large build files into logical components (common-build.xml, test-build.xml) وإدراجها لتحسين قابلية الصيانة.
توثيق المنطق المعقد بالتعليقات: استخدم تعليقات XML لشرح منطق البناء غير الواضح، واستخدام الخصائص، والاعتمادات، خاصة في المشاريع المشتركة أو القديمة.

استكشاف الأخطاء وإصلاحها

مشكلة	حل
`BUILD FAILED: build.xml does not exist`	Run `ant -find` to search parent directories, or specify file with `ant -f path/to/build.xml`
`Unable to locate tools.jar`	Set `JAVA_HOME` to JDK (not JRE) directory. Verify with `echo $JAVA_HOME` and ensure it points to JDK installation
`ClassNotFoundException` for custom tasks	Add JAR to Ant’s classpath using `-lib` option: `ant -lib /path/to/jars compile` or use `<taskdef>` with correct classpath
Compilation fails with encoding errors	Add `encoding="UTF-8"` attribute to `<javac>` task: `<javac srcdir="${src.dir}" encoding="UTF-8"/>`
Out of memory during build	Increase heap size: `export ANT_OPTS="-Xmx1024m -Xms512m"` (Linux/Mac) or `set ANT_OPTS=-Xmx1024m` (Windows)
Target not found error	Verify target name with `ant -projecthelp`. Check for typos and ensure target is defined in active build file
Circular dependency detected	Review `depends` attributes in targets. Ant cannot resolve circular references - redesign target dependencies
Permission denied when writing files	تحقق من أذونات الدليل وتأكد من أن Ant لديه حق الوصول للكتابة. قم بالتشغيل مع امتيازات المستخدم المناسبة أو قم بتعديل ملكية الدليل
`fork="true"` required but task fails	Some tasks (junit, java) require forking. Ensure `fork="true"` is set and `JAVA_HOME` points to valid JDK
Properties not being overridden	Properties are immutable in Ant - first definition wins. Set properties via command line (`-D`) before build file loads them
Slow builds with large filesets	Use `<uptodate>` conditions for incremental builds. Enable parallel execution with `-Dant.executor.class=org.apache.tools.ant.helper.ParallelExecutor`
JAR file manifest not correct	Use `<manifest>` element within `<jar>` task to specify Main-Class and other attributes explicitly

مرجع مهام Ant الشائعة

مهمة	وصف	مثال
`<javac>`	قم بتجميع ملفات مصدر Java	`<javac srcdir="src" destdir="build" includeantruntime="false"/>`
`<jar>`	إنشاء أرشيف JAR	`<jar destfile="dist/app.jar" basedir="build"/>`
`<war>`	إنشاء أرشيف WAR	`<war destfile="dist/app.war" webxml="web/WEB-INF/web.xml"/>`
`<copy>`	نسخ الملفات أو المجلدات	`<copy todir="backup"><fileset dir="src"/></copy>`
`<delete>`	حذف الملفات أو المجلدات	`<delete dir="build"/>`
`<mkdir>`	أنشئ مجلد	`<mkdir dir="dist"/>`
`<echo>`	اطبع الرسالة	`<echo message="Building version ${version}"/>`
`<exec>`	تنفيذ أمر النظام	`<exec executable="git" args="rev-parse HEAD"/>`
`<junit>`	قم بتشغيل اختبارات JUnit	`<junit printsummary="yes" fork="yes"/>`
`<zip>`	إنشاء أرشيف ZIP	`<zip destfile="dist/src.zip" basedir="src"/>`
`<sql>`	نفّذ عبارات SQL	`<sql driver="${db.driver}" url="${db.url}" src="schema.sql"/>`